N8n Agent

Autonomous AI agent for n8n workflow automation with credential factories, execution helpers, 4343+ workflow templates, and specialized sub-agents.

npm version License: MIT

Features

• 38 MCP Tools - Full n8n API coverage for workflows, executions, credentials, tags, variables, and more
• 4343+ Workflow Templates - Access to Zie619 database with 268 integrations across 16 categories
• Credential Factories - Type-safe factories for Google, Postgres, Slack, Telegram, OpenAI, GitHub, and more
• Execution Helpers - Wait for completion, extract output data, get errors, batch operations
• Workflow Helpers - Webhook URL extraction, duplication with credential stripping, node management
• Auto-Connect - Automatic connection from environment variables (N8N_URL, N8N_API_KEY)
• TypeScript First - Built with TypeScript, well-tested with 205+ tests

Installation

Get your n8n API Key

1. Log into your n8n instance
2. Click your user icon in the bottom left
3. Go to Settings
4. Select API
5. Click "Create API Key"
6. Copy your API key (you will not be able to see it again)

Install from npm

npm install -g @anatolykoptev/n8n-mcp-agent

Install from Source

git clone https://github.com/anatolykoptev/n8n-mcp-agent.git
cd n8n-mcp-agent
npm install
npm run build

Configuration

Claude Desktop

Open your Claude Desktop configuration file:

~/Library/Application Support/Claude/claude_desktop_config.json

Add the n8n configuration:

{
  "mcpServers": {
    "n8n": {
      "command": "n8n-mcp-agent",
      "env": {
        "N8N_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cline (VS Code)

1. Open VS Code
2. Open the Cline extension from the left sidebar
3. Click the "MCP Servers" icon at the top of the pane
4. Scroll to bottom and click "Configure MCP Servers"
5. Add to the opened settings file:

{
  "mcpServers": {
    "n8n": {
      "command": "n8n-mcp-agent",
      "env": {
        "N8N_URL": "https://your-n8n-instance.com",
        "N8N_API_KEY": "your-api-key-here"
      }
    }
  }
}

Environment Variables

The server auto-connects when these environment variables are set:

Variable	Description
N8N_URL	Your n8n instance URL (e.g., https://n8n.example.com)
N8N_API_KEY	Your n8n API key

MCP Tools

Workflow Management (8 tools)

• init-n8n - Initialize connection to n8n instance
• list-workflows - List all workflows
• get-workflow - Get workflow by ID
• create-workflow - Create new workflow
• update-workflow - Update existing workflow
• delete-workflow - Delete workflow
• activate-workflow - Activate workflow
• deactivate-workflow - Deactivate workflow

Execution Management (3 tools)

• list-executions - List executions with filters
• get-execution - Get execution by ID
• delete-execution - Delete execution

Credential Management (3 tools)

• create-credential - Create credential
• delete-credential - Delete credential
• get-credential-schema - Get schema for credential type

Tag Management (7 tools)

• list-tags - List all tags
• create-tag - Create new tag
• get-tag - Get tag by ID
• update-tag - Update tag name
• delete-tag - Delete tag
• get-workflow-tags - Get tags for workflow
• update-workflow-tags - Update workflow tags

User Management (4 tools)

• list-users - List all users
• create-users - Create users
• get-user - Get user by ID or email
• delete-user - Delete user

Project Management (4 tools, Enterprise)

• list-projects - List all projects
• create-project - Create project
• update-project - Update project
• delete-project - Delete project

Variable Management (3 tools, Enterprise)

• list-variables - List all variables
• create-variable - Create variable
• delete-variable - Delete variable

Security (1 tool)

• generate-audit - Generate security audit

Workflow Templates (5 tools)

• n8n-patterns-stats - Get database statistics
• n8n-patterns-search - Search templates
• n8n-patterns-get - Get template by ID
• n8n-patterns-categories - List categories
• n8n-patterns-integrations - List top integrations

Credential Factories

Type-safe factory methods for creating credentials programmatically:

// Available factories
createGoogleServiceAccount(name, email, privateKey)
createPostgres(name, host, database, user, password, port?, ssl?)
createHttpBasic(name, username, password)
createApiKey(name, apiKey, headerName?)
createSlack(name, accessToken)
createTelegram(name, accessToken)
createOpenAI(name, apiKey)
createAirtable(name, apiKey)
createNotion(name, apiKey)
createGitHub(name, accessToken)
createSmtp(name, host, port, user, password, secure?)
createMySql(name, host, database, user, password, port?)

Execution Helpers

Advanced execution monitoring and data extraction:

// Wait for execution to complete with polling
waitForCompletion(executionId, timeout?, pollInterval?)

// Extract output data from execution
getOutput(executionId)

// Get error message from failed execution
getError(executionId)

// Check if execution is running
isRunning(executionId)

// List failed executions
listFailed(workflowId?, limit?)

// List running executions
listRunning(workflowId?, limit?)

// Delete multiple executions
deleteMany({ workflowId?, status?, limit? })

Workflow Helpers

Advanced workflow manipulation:

// Extract webhook URL from workflow
getWebhookUrl(workflowId)

// Duplicate workflow with credential stripping
duplicate(sourceId, newName, stripCredentials?)

// Add node to existing workflow
addNode(workflowId, node)

// Create workflow with trigger
createWithTrigger(name, triggerType, triggerConfig?)

// Get workflow statistics
getStats(workflowId)

Workflow Templates

Access 4343+ workflow templates from the Zie619 database:

• 268 integrations - Shopify, OpenAI, Slack, Telegram, GitHub, and more
• 16 categories - E-commerce, AI Agent Development, Marketing, CRM, and more
• Complexity levels - Low, Medium, High
• Trigger types - Manual, Webhook, Scheduled, Complex

Validation

After configuration:

1. Restart your LLM application
2. Ask: "List my n8n workflows"
3. You should see your workflows listed

If you get an error:

• Check that your n8n instance is running
• Verify your API key has correct permissions
• Ensure N8N_URL has no trailing slash

Troubleshooting

Common Issues

1. "Client not initialized"

   • Check N8N_URL and N8N_API_KEY are set correctly
   • Ensure n8n instance is accessible
   • Verify API key permissions

2. "License required"

   • You are trying to use an Enterprise feature
   • Either upgrade to n8n Enterprise or use core features only

3. Connection Issues

   • Verify n8n instance is running
   • Check URL protocol (http/https)
   • Remove trailing slash from N8N_URL

Security Best Practices

1. API Key Management

   • Use minimal permissions necessary
   • Rotate keys regularly
   • Never commit keys to version control

2. Instance Access

   • Use HTTPS for production
   • Enable n8n authentication
   • Keep n8n updated

Support

• GitHub Issues
• n8n Documentation

Author

Anatoly Koptev

License

MIT License