mcp-n8n-builder

A Model Context Protocol (MCP) server for programmatic creation and management of n8n workflows. This server provides tools and resources for interacting with n8n's REST API, allowing AI assistants to build, modify, and manage workflows without direct user intervention.

Features

🔄 Workflow Management: Create, read, update, delete, activate, and deactivate workflows
📊 Execution Management: List and retrieve workflow execution details
✅ Schema Validation: Comprehensive validation with Zod for both input and output data
🔍 Node Validation: Validates node types against n8n's available nodes before workflow creation to prevent errors
🤔 Smart Suggestions: Provides suggestions for similar node types when invalid nodes are detected
🛠️ Error Handling: Detailed error messages for troubleshooting
📝 Documentation: Extensive documentation for all tools and resources
🔍 Search & Filter: Filter workflows by name, tags, or active status

⚠️ Token Consumption Warning

This tool is a "token monster" due to the nature of n8n workflows:

N8N workflows are complex JSON structures with nested nodes, connections, parameters, and settings
A single workflow can easily consume thousands of tokens when viewed or edited
The JSON structure cannot be meaningfully reduced without losing essential workflow information
LLM context windows are finite - complex workflows may exceed available context

Mitigation Strategies

The tool implements several optimizations to reduce token usage:

Verbosity Control: Use OUTPUT_VERBOSITY=concise (default) for summaries instead of full JSON
Object Simplification: Workflow listings show only essential fields (id, name, status, node count)
Selective Guide Inclusion: Error messages include only relevant sections of the composition guide
Per-tool Verbosity: Override verbosity on individual tool calls with the verbosity parameter

Recommended Usage

List workflows first to identify what you need (low token cost)
Work with simple workflows when possible
Use concise verbosity unless you specifically need full JSON
Break complex workflows into smaller pieces for easier management
Consider the token cost before retrieving or editing large workflows

Configuration

This server requires configuration through your MCP client. Here are examples for different environments:

Cline Configuration

Add this to your Cline MCP settings:

{
	"mcpServers": {
		"n8n-workflow-builder": {
			"command": "npx",
			"args": ["-y", "mcp-n8n-builder"],
			"env": {
				"N8N_HOST": "http://localhost:5678/api/v1",
				"N8N_API_KEY": "your-n8n-api-key",
				"OUTPUT_VERBOSITY": "concise" // Options: 'concise' or 'full'
			}
		}
	}
}

Claude Desktop with WSL Configuration

For WSL environments, add this to your Claude Desktop configuration:

{
	"mcpServers": {
		"n8n-workflow-builder": {
			"command": "wsl.exe",
			"args": [
				"bash",
				"-c",
				"N8N_HOST=http://localhost:5678/api/v1 N8N_API_KEY=your-n8n-api-key OUTPUT_VERBOSITY=concise npx -y mcp-n8n-builder"
			]
		}
	}
}

Environment Variables

The server can be configured using environment variables:

Variable	Description	Default
`N8N_HOST`	URL of the n8n API	`http://localhost:5678/api/v1`
`N8N_API_KEY`	API key for n8n authentication	`""`
`SERVER_NAME`	Name of the MCP server	`"n8n-workflow-builder"`
`SERVER_VERSION`	Version of the MCP server	Package version
`LOG_LEVEL`	Logging level	`"info"`
`CACHE_ENABLED`	Enable caching	`false`
`CACHE_TTL`	Cache TTL in seconds	`300`
`OUTPUT_VERBOSITY`	Output verbosity level (`concise` or `full`)	`"concise"`

MCP Tools

Node Management

list_available_nodes: Lists all available nodes in the n8n instance. IMPORTANT: Use this tool BEFORE creating or updating workflows to ensure you only use valid node types. This helps prevent errors caused by using node types that don't exist in the current n8n instance.

Workflow Management

list_workflows: Lists all workflows from n8n with their basic information including ID, name, status, creation date, and tags. Results can be filtered by active status, tags, or name.
create_workflow: Creates a new workflow in n8n with specified nodes and connections. Returns the created workflow with its assigned ID. Validates that all node types exist in the n8n instance.
get_workflow: Retrieves complete details of a specific workflow by its ID, including all nodes, connections, settings, and metadata.
update_workflow: Updates an existing workflow with new configuration. The entire workflow structure must be provided, not just the parts being changed. Validates that all node types exist in the n8n instance.
delete_workflow: Permanently deletes a workflow by its ID. This action cannot be undone.
activate_workflow: Activates a workflow by its ID, enabling it to run automatically based on its trigger.
deactivate_workflow: Deactivates a workflow by its ID, preventing it from running automatically.

Execution Management

list_executions: Lists workflow execution history with details on success/failure status, duration, and timestamps. Results can be filtered by workflow ID, status, and limited to a specific number.
get_execution: Retrieves detailed information about a specific workflow execution, including execution time, status, and optionally the full data processed at each step.

MCP Resources

n8n://workflows: List of all workflows in n8n
n8n://workflows/{id}: Details of a specific n8n workflow
n8n://executions/{id}: Details of a specific n8n workflow execution

Development

Setup

Clone the repository
Install dependencies:

npm install

Build the project:

npm run build

Run in development mode:

npm run dev

Publishing

The project uses changesets for version management. To publish:

Create a changeset:

npm changeset

Version the package:

npm changeset version

Publish to npm:

npm release

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.

Acknowledgments

Built on the Model Context Protocol
Powered by n8n