Model Context Protocol server for n8n workflow management
npm install @makafeli/n8n-workflow-builderA 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.
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.
- 🔧 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
- Node.js v18.0.0 or higher
- n8n instance (self-hosted or cloud)
- n8n API key with appropriate permissions
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.
Run locally with NPX:
``bash`
npx @makafeli/n8n-workflow-builder
For development or customization:
`bashClone the repository
git clone https://github.com/makafeli/n8n-workflow-builder.git
cd n8n-workflow-builder
⚙️ Configuration
$3
Configure the following environment variables to connect to your n8n instance:
| 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
export N8N_HOST="http://localhost:5678"
export N8N_API_KEY="your-api-key-here"Then run the server
npx @makafeli/n8n-workflow-builder
`🔧 MCP Client Setup
$3
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
``1. Check the GitHub Issues
2. Review n8n's API documentation
3. Verify your MCP client configuration
We welcome contributions!
This project is licensed under the MIT License - see the LICENSE file for details.
- 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