n8n Workflow Builder MCP Server

A powerful Model Context Protocol (MCP) server that enables AI assistants to manage n8n workflows seamlessly. Connect your AI tools directly to n8n for automated workflow creation, execution, and management.

🎯 What is this?

The n8n Workflow Builder MCP Server bridges the gap between AI assistants (like Claude Desktop, Cline, or any MCP-compatible client) and your n8n automation platform. It provides a comprehensive set of tools that allow AI assistants to:

- List and browse your existing n8n workflows
- Create new workflows with complex node configurations
- Execute workflows on demand
- Manage workflow lifecycle (activate, deactivate, update, delete)
- Monitor workflow status and retrieve detailed information

Perfect for teams using n8n who want to leverage AI assistants for workflow automation and management.

✨ Key Features

- 🔧 Complete Workflow Management - Full CRUD operations for n8n workflows
- 🤖 AI-First Design - Built specifically for AI assistant integration
- 🚀 Zero Configuration - Works out of the box with NPX
- 🔒 Secure - Uses n8n's official API with proper authentication
- 📦 Modern Architecture - Built with TypeScript and latest MCP SDK
- ⚡ High Performance - Optimized for fast response times

📋 Requirements

- Node.js v18.0.0 or higher
- n8n instance (self-hosted or cloud)
- n8n API key with appropriate permissions

🚀 Installation & Usage

$3

Use the hosted version on Smithery.ai - no installation required:

1. Visit: smithery.ai
2. Search: "n8n-workflow-builder"
3. Connect: Configure with your n8n host and API key
4. Use: Access from any MCP-compatible AI assistant

Benefits: No local setup, automatic updates, professional hosting, tool playground.

$3

Run locally with NPX:

``bash
npx @makafeli/n8n-workflow-builder
`

$3

For development or customization:

`bash


Clone the repository

| Variable | Description | Example |
|----------|-------------|---------|
| N8N_HOST | Your n8n instance URL | http://localhost:5678 or https://your-n8n.com/api/v1 |
| N8N_API_KEY | Your n8n API key | n8n_api_1234567890abcdef... |

$3

1. Open your n8n instance
2. Go to Settings → API Keys
3. Click Create API Key
4. Copy the generated key

$3

`bash


For local testing

Add this configuration to your claude_desktop_config.json:

`json
{
"mcpServers": {
"n8n-workflow-builder": {
"command": "npx",
"args": ["@makafeli/n8n-workflow-builder"],
"env": {
"N8N_HOST": "http://localhost:5678",
"N8N_API_KEY": "your-api-key-here"
}
}
}
}
`

$3

Add this to your Cline MCP settings:

`json
{
"mcpServers": {
"n8n-workflow-builder": {
"command": "npx",
"args": ["@makafeli/n8n-workflow-builder"],
"env": {
"N8N_HOST": "http://localhost:5678",
"N8N_API_KEY": "your-api-key-here"
}
}
}
}
`

$3

The server works with any MCP-compatible client. Use the same configuration pattern with your client's specific setup method.

🛠️ Available Tools

The MCP server provides 15 comprehensive tools for complete n8n workflow and execution management:

$3

| Tool | Description | Parameters |
|------|-------------|------------|
| list_workflows | List all workflows from your n8n instance | None |
| get_workflow | Retrieve detailed information about a specific workflow | id: Workflow ID (string) |
| create_workflow | Create a new workflow with nodes and connections | workflow: Workflow object |
| execute_workflow | Manually execute a workflow | id: Workflow ID (string) |

$3

| Tool | Description | Parameters |
|------|-------------|------------|
| update_workflow | Update an existing workflow's configuration | id: Workflow ID, workflow: Updated workflow object |
| activate_workflow | Activate a workflow to enable automatic execution | id: Workflow ID (string) |
| deactivate_workflow | Deactivate a workflow to stop automatic execution | id: Workflow ID (string) |
| delete_workflow | Permanently delete a workflow | id: Workflow ID (string) |

$3

| Tool | Description | Parameters |
|------|-------------|------------|
| create_workflow_and_activate | Create a new workflow and immediately activate it | workflow: Workflow object |

$3

| Tool | Description | Parameters |
|------|-------------|------------|
| list_executions | List workflow executions with filtering and pagination | includeData, status, workflowId, projectId, limit, cursor |
| get_execution | Get detailed information about a specific execution | id: Execution ID, includeData: Include detailed data |
| delete_execution | Delete a workflow execution record | id: Execution ID |

$3

| Tool | Description | Parameters |
|------|-------------|------------|
| list_tags | List all workflow tags with pagination | limit, cursor |
| create_tag | Create a new workflow tag for organization | name: Tag name |

$3

| Tool | Description | Parameters |
|------|-------------|------------|
| generate_audit | Generate comprehensive security audit report | additionalOptions: Audit configuration |

💡 Usage Examples

$3

`javascript
// List all workflows
await callTool("list_workflows", {});

// Get detailed information about a workflow
await callTool("get_workflow", { id: "workflow-123" });

// Execute a workflow manually
await callTool("execute_workflow", { id: "workflow-123" });
`

$3

`javascript
// Create a simple workflow
await callTool("create_workflow", {
workflow: {
name: "My Automation Workflow",
nodes: [
{
id: "trigger",
name: "Schedule Trigger",
type: "n8n-nodes-base.scheduleTrigger",
typeVersion: 1,
position: [240, 300],
parameters: {
interval: [{ field: "unit", value: "hours" }]
}
},
{
id: "action",
name: "HTTP Request",
type: "n8n-nodes-base.httpRequest",
typeVersion: 4,
position: [460, 300],
parameters: {
url: "https://api.example.com/webhook",
method: "POST"
}
}
],
connections: {
"Schedule Trigger": {
"main": [[{ "node": "HTTP Request", "type": "main", "index": 0 }]]
}
}
}
});
`

$3

`javascript
// Activate a workflow
await callTool("activate_workflow", { id: "workflow-123" });

// Update a workflow
await callTool("update_workflow", {
id: "workflow-123",
workflow: { name: "Updated Workflow Name" }
});

// Deactivate a workflow
await callTool("deactivate_workflow", { id: "workflow-123" });

// Create and immediately activate
await callTool("create_workflow_and_activate", {
workflow: { / workflow configuration / }
});
`

$3

`javascript
// List recent executions
await callTool("list_executions", {
limit: 10,
status: "error"
});

// Get detailed execution information
await callTool("get_execution", {
id: "execution-123",
includeData: true
});

// Clean up old execution records
await callTool("delete_execution", { id: "execution-123" });
`

$3

`javascript
// List all workflow tags
await callTool("list_tags", { limit: 50 });

// Create a new tag for organization
await callTool("create_tag", { name: "production" });
`

$3

`javascript
// Generate comprehensive security audit
await callTool("generate_audit", {
additionalOptions: {
daysAbandonedWorkflow: 30,
categories: ["credentials", "database", "nodes"]
}
});
`

🔧 Troubleshooting

$3

#### "Connection refused" or "ECONNREFUSED"
- Cause: Cannot connect to your n8n instance
- Solution: Verify your N8N_HOST is correct and n8n is running
- Check: Try accessing your n8n instance in a browser first

#### "Unauthorized" or "401 Error"
- Cause: Invalid or missing API key
- Solution:
1. Verify your N8N_API_KEY is correct
2. Ensure the API key has proper permissions
3. Check if the API key hasn't expired

#### "Workflow not found" or "404 Error"
- Cause: Workflow ID doesn't exist
- Solution: Use list_workflows to get valid workflow IDs

#### Server won't start
- Cause: Missing Node.js or dependencies
- Solution:
1. Ensure Node.js v18+ is installed: node --version
2. Try clearing npm cache: npm cache clean --force
3. For manual installation, run: npm install && npm run build

$3

For detailed logging, set the debug environment variable:

`bash
DEBUG=n8n-workflow-builder npx @makafeli/n8n-workflow-builder
``

$3

1. Check the GitHub Issues
2. Review n8n's API documentation
3. Verify your MCP client configuration

🤝 Contributing

We welcome contributions!

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Useful Links

- n8n Documentation - Official n8n docs
- Model Context Protocol - MCP specification
- Claude Desktop - AI assistant with MCP support
- Cline - VS Code AI assistant
- GitHub Repository - Source code and issues

---

Built with ❤️ for the n8n and MCP community