mcp-n8n-builder

mcp-n8n-builder

A Model Context Protocol (MCP) server for programmatic creation andmanagement of n8n workflows. This server provides tools and resourcesfor 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 executiondetails
• ✅ Schema Validation: Comprehensive validation with Zod for bothinput and output data
• 🔍 Node Validation: Validates node types against n8n's availablenodes before workflow creation to prevent errors
• 🤔 Smart Suggestions: Provides suggestions for similar nodetypes when invalid nodes are detected
• 🛠️ Error Handling: Detailed error messages for troubleshooting
• 📝 Documentation: Extensive documentation for all tools andresources
• 🔍 Search & Filter: Filter workflows by name, tags, or activestatus

Configuration

This server requires configuration through your MCP client. Here areexamples 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:

MCP Tools

Node Management

• list_available_nodes: Lists all available nodes in the n8ninstance. IMPORTANT: Use this tool BEFORE creating or updatingworkflows to ensure you only use valid node types. This helpsprevent errors caused by using node types that don't exist in thecurrent n8n instance.

Workflow Management

• list_workflows: Lists all workflows from n8n with their basicinformation 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 specifiednodes and connections. Returns the created workflow with itsassigned ID. Validates that all node types exist in the n8ninstance.
• get_workflow: Retrieves complete details of a specific workflow byits ID, including all nodes, connections, settings, and metadata.
• update_workflow: Updates an existing workflow with newconfiguration. The entire workflow structure must be provided, notjust the parts being changed. Validates that all node types exist inthe n8n instance.
• delete_workflow: Permanently deletes a workflow by its ID. Thisaction cannot be undone.
• activate_workflow: Activates a workflow by its ID, enabling it torun automatically based on its trigger.
• deactivate_workflow: Deactivates a workflow by its ID, preventingit from running automatically.

Execution Management

• list_executions: Lists workflow execution history with details onsuccess/failure status, duration, and timestamps. Results can befiltered by workflow ID, status, and limited to a specific number.
• get_execution: Retrieves detailed information about a specificworkflow execution, including execution time, status, and optionallythe 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 workflowexecution

Development

Setup

1. Clone the repository
2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Run in development mode:

npm run dev

Publishing

The project uses changesets for version management. To publish:

1. Create a changeset:

npm changeset

2. Version the package:

npm changeset version

3. 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 theModel Context Protocol
• Powered by n8n