--- slug: "n8n-mcp-server" source_type: "readme" source_url: "https://cdn.jsdelivr.net/gh/visccyberacct/n8n-mcp-server@main/README.md" repo: "https://github.com/visccyberacct/n8n-mcp-server" source_file: "README.md" branch: "main" --- # n8n MCP Server MCP server providing tools to interact with the n8n workflow automation platform at n8n.homelab.com. ## Features - **30 n8n API tools** for complete workflow automation - Full workflow CRUD operations (Create, Read, Update, Delete) - Workflow health monitoring and cloning - Credential and tag management - Client-side workflow filtering (name, active status, tags) - Pre-submission workflow validation - Async/await support for all operations - Secure API key authentication - SSL/TLS support for homelab environments - Complete type hints and documentation - Production-ready error handling - 139 tests with comprehensive code coverage ## Tools ### Workflow Management - `list_workflows` - List workflows with optional filtering (name, active, tags) - `get_workflow` - Get specific workflow by ID - `create_workflow` - Create new workflows programmatically - `update_workflow` - Update existing workflow configuration - `delete_workflow` - Delete workflows by ID - `activate_workflow` - Activate or deactivate a workflow - `deactivate_workflow` - Deactivate a workflow - `get_workflow_version` - Get a specific version of a workflow - `transfer_workflow` - Transfer workflow to a different project - `get_workflow_tags` - Get tags assigned to a workflow - `update_workflow_tags` - Update tags assigned to a workflow - `clone_workflow` - Clone a workflow with automatic field cleanup - `validate_workflow` - Validate workflow structure before creating ### Workflow Execution - `execute_workflow` - Trigger workflow execution - `get_executions` - List workflow execution history - `get_execution` - Get specific execution details by ID - `delete_execution` - Delete an execution history entry - `retry_execution` - Retry a failed execution ### Workflow Analysis - `get_workflow_health` - Analyze workflow health based on recent executions ### Credential Management - `list_credentials` - List all credentials (IDs only, data redacted) - `create_credential` - Create a new credential - `update_credential` - Update an existing credential - `delete_credential` - Delete a credential - `get_credential_schema` - Get schema for a credential type - `transfer_credential` - Transfer credential to a different project ### Tag Management - `list_tags` - List all tags - `create_tag` - Create a new tag - `get_tag` - Get a specific tag by ID - `update_tag` - Update an existing tag - `delete_tag` - Delete a tag ## Installation ### Prerequisites - Python 3.12 or higher - n8n instance with API access (n8n.homelab.com) - Claude CLI installed (`curl -sSL https://claude.ai/install | bash`) ### Setup ```bash cd ~/projects/n8n-mcp-server # Create virtual environment and install uv venv source .venv/bin/activate # or .venv\Scripts\activate on Windows uv pip install -e ".[dev]" ``` ### Configuration ```bash # Copy example environment file cp .env.example .env # Edit .env with your n8n API key # N8N_API_KEY=your_actual_api_key_here ``` ## Usage with Claude Code ### Register MCP Server ```bash claude mcp add n8n-api \ --env N8N_BASE_URL=https://n8n.homelab.com \ --env N8N_API_KEY=your_key_here \ --scope user -- \ python -m n8n_mcp.server ``` ### Example Usage Once registered, ask Claude Code: **Workflow Management:** - "List all my n8n workflows" - "Create a simple workflow with a Start node" - "Update workflow abc123 to change its name" - "Delete workflow xyz789" - "Activate workflow abc123" **Workflow Execution:** - "Execute workflow ID abc123" - "Show me the last 10 workflow executions" - "Get details for execution exec-456" **Example: Create a Workflow** ```json { "name": "My New Workflow", "nodes": [ { "id": "start-node", "name": "Start", "type": "n8n-nodes-base.start", "typeVersion": 1, "position": [250, 300], "parameters": {} } ], "connections": {}, "settings": {} } ``` ## Development ### Run Tests ```bash # Run all tests pytest # Run with coverage pytest --cov=n8n_mcp --cov-report=term-missing # Run specific test file pytest tests/test_server.py -v ``` ### Code Quality ```bash # Format code ruff format src tests # Lint code ruff check src tests # Type check mypy src ``` ## API Compatibility Compatible with n8n REST API v1. Tested against n8n version 1.x. The following n8n API endpoints are supported: - `GET /api/v1/workflows` - List all workflows - `GET /api/v1/workflows/{id}` - Get workflow details - `POST /api/v1/workflows` - Create new workflow - `PUT /api/v1/workflows/{id}` - Update workflow - `DELETE /api/v1/workflows/{id}` - Delete workflow - `PATCH /api/v1/workflows/{id}` - Update workflow (activate/deactivate) - `POST /api/v1/workflows/{id}/execute` - Execute workflow - `GET /api/v1/executions` - List executions - `GET /api/v1/executions/{id}` - Get execution details ## Troubleshooting ### Authentication Errors **Issue**: Getting "Not authorized" or "401 Unauthorized" errors **Solution**: - Verify N8N_API_KEY is correct - Ensure you're using a USER token (not project token) - Check the API key has proper permissions in n8n ### Connection Errors **Issue**: Cannot connect to n8n instance **Solution**: - Verify N8N_BASE_URL is correct (https://n8n.homelab.com) - Check network access to n8n instance - Verify n8n instance is running - Check firewall rules if applicable - For SSL certificate errors in homelab environments, the client automatically disables SSL verification (verify_ssl=False) ### Tool Not Found **Issue**: Claude Code says n8n tools are not available **Solution**: - Ensure MCP server is registered correctly: `claude mcp list` - Verify environment variables are set in registration command - Restart Claude Code after registration - Check MCP server logs for errors ### Import Errors **Issue**: Module import errors when running the server **Solution**: - Ensure virtual environment is activated - Run `poetry install` or `uv pip install -e .` - Verify Python version is 3.11+ ## Example Workflows ### Ubuntu/Debian Server Updates A pre-built workflow for automating system updates on Ubuntu and Debian servers via SSH. **Workflow ID**: `Ikau3rRnpRG1okvq` See [N8N_SERVER_UPDATE_WORKFLOW.md](https://github.com/visccyberacct/n8n-mcp-server/blob/HEAD/docs/N8N_SERVER_UPDATE_WORKFLOW.md) for: - Complete configuration guide - SSH setup instructions - Security best practices - Scheduling options - Troubleshooting tips **Quick Start**: 1. Open workflow in n8n: https://n8n.homelab.com/workflow/Ikau3rRnpRG1okvq 2. Configure SSH credentials 3. Update server list in "Set Server List" node 4. Test with manual trigger 5. Activate for production use ## Project Structure ``` n8n-mcp-server/ ├── src/n8n_mcp/ │ ├── __init__.py # Package initialization │ ├── server.py # FastMCP server with 30 tools │ ├── client.py # n8n API client wrapper (SSL support) │ ├── validator.py # Workflow validation utilities │ ├── models.py # Pydantic models for n8n data │ └── utils.py # Shared utilities ├── tests/ │ ├── __init__.py │ └── test_server.py # 139 tests with comprehensive coverage ├── docs/ │ ├── N8N_API_WORKFLOW_CREATION_REPORT.md # Detailed API research │ ├── N8N_SERVER_UPDATE_WORKFLOW.md # Server update workflow guide │ ├── CREDENTIAL_TYPES.md # Credential type reference │ ├── CONNECTION_TYPES.md # Connection type reference │ └── KNOWN_LIMITATIONS.md # API limitations and workarounds ├── pyproject.toml # Project dependencies ├── README.md # This file └── .env.example # Example configuration ``` ## License MIT License - See LICENSE file for details ## Contributing Contributions welcome! Please ensure: - All tests pass (`pytest`) - Code is formatted (`ruff format src tests`) - Code is linted (`ruff check src tests`) - Type hints are provided (`mypy src`) - Documentation is updated ## Support For issues, questions, or contributions, please contact the maintainer or open an issue in the project repository.