n8n MCP Server 🚀

Professional MCP (Model Context Protocol) server for managing n8n workflows programmatically. Enables AI assistants like Claude, GPT, and others to create, manage, and orchestrate n8n workflows seamlessly.

🚀 Quick Start

Get up and running in minutes with Docker:

1. Clone the repository:

   git clone https://github.com/MrBozkay/n8n-mcp-server.git
   cd n8n-mcp-server
   

2. Build the Docker image:

   docker build -t n8n-mcp-server .
   

3. Run the container: Replace the placeholder values for N8N_BASE_URL and N8N_API_KEY with your actual n8n credentials.

   docker run -d -p 8080:8080 \
     -e N8N_BASE_URL="https://your-instance.app.n8n.cloud" \
     -e N8N_API_KEY="your-n8n-api-key" \
     --name n8n-mcp-container \
     n8n-mcp-server
   

4. Connect your MCP client: Point your MCP client (e.g., Claude Desktop) to http://localhost:8080.

For more detailed instructions, see the Installation and Usage sections.

🎯 Project Goals

Main Purpose

Empower AI assistants to programmatically manage n8n workflows through a standardized, secure interface.

Business Objectives

• ✅ Enable AI-driven workflow automation
• ✅ Streamline workflow creation, search, and management
• ✅ Secure and efficient n8n API integration
• ✅ Developer-friendly tooling and documentation

Success Criteria

• ✅ 100% functional CRUD operations for workflows
• ✅ API response time < 2 seconds
• ✅ Error rate < 1%
• ✅ Full MCP protocol compliance
• ✅ Comprehensive documentation and examples

✨ Features

Core Operations

• Create Workflow: Build new n8n workflows with nodes and connections
• Get Workflow: Retrieve workflow details by ID
• List Workflows: Browse workflows with filtering (active, tags, pagination)
• Search Workflows: Find workflows by name or tags
• Update Workflow: Modify existing workflows
• Delete Workflow: Remove workflows safely
• Activate/Deactivate: Control workflow execution state
• Health Check: Monitor API connection status

Technical Features

• 🔐 Secure Authentication: API key-based authentication
• ⚡ Performance: Built-in caching with configurable TTL
• 🔄 Retry Mechanism: Automatic retry with exponential backoff
• 📊 Comprehensive Logging: Structured logging with different levels
• 🛡️ Error Handling: Robust error handling and recovery
• 🔌 MCP Protocol: Full compliance with MCP standard

📋 Prerequisites

• Python: 3.8 or higher
• n8n Instance: Cloud or self-hosted with API access
• n8n API Key: How to create
• MCP Client: Claude Desktop, or any MCP-compatible AI assistant

🛠 Installation

Method 1: Using Docker (Recommended for Production & AI Assistants)

Docker, projenin tüm bağımlılıklarıyla birlikte izole bir ortamda çalışmasını sağlar ve en stabil yöntemdir.

1. Docker imajını oluşturun: Projenin ana dizininde aşağıdaki komutu çalıştırın:

   docker build -t n8n-mcp-server .
   

2. Konteyneri Çalıştırın: Aşağıdaki komutu kullanarak konteyneri başlatın. Bu komut, sunucuyu arka planda başlatır ve makinenizin 8080 portunu konteynerin 8080 portuna yönlendirir.

   Önemli: Komutu çalıştırmadan önce -e ile belirtilen N8N_BASE_URL ve N8N_API_KEY ortam değişkenlerini kendi n8n bilgilerinizle değiştirmeyi unutmayın.

   docker run -d -p 8080:8080 \
     -e N8N_BASE_URL="https://your-instance.app.n8n.cloud" \
     -e N8N_API_KEY="your-n8n-api-key" \
     --name n8n-mcp-container \
     n8n-mcp-server
   

3. Logları Kontrol Edin: Konteynerin durumunu ve loglarını kontrol etmek için aşağıdaki komutu kullanabilirsiniz:

   docker logs -f n8n-mcp-container
   

Method 2: From Source (For Development)

# Clone the repository
git clone https://github.com/yourusername/n8n-mcp-server.git
cd n8n-mcp-server

# Create and activate a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Set up configuration
cp config/config.example.json config/config.json
# Edit config/config.json with your n8n instance details

Method 2: Using pip (Coming Soon)

pip install n8n-mcp-server

⚙️ Configuration

Option 1: JSON Configuration File

Create config/config.json:

{
  "n8n": {
    "base_url": "https://your-instance.app.n8n.cloud",
    "api_key": "your-n8n-api-key-here",
    "timeout": 30,
    "max_retries": 3
  },
  "mcp": {
    "server_name": "n8n-mcp-server",
    "version": "1.0.0"
  },
  "logging": {
    "level": "INFO",
    "file_path": "logs/n8n_mcp_server.log"
  },
  "performance": {
    "cache_ttl": 300
  }
}

Option 2: Environment Variables

Create .env file:

N8N_BASE_URL=https://your-instance.app.n8n.cloud
N8N_API_KEY=your-n8n-api-key-here
N8N_TIMEOUT=30
N8N_MAX_RETRIES=3
MCP_SERVER_NAME=n8n-mcp-server
MCP_VERSION=1.0.0
LOG_LEVEL=INFO
LOG_FILE_PATH=logs/n8n_mcp_server.log
CACHE_TTL=300

Then run with:

python -m src.n8n_mcp.server --env

🚀 Usage

Starting the Server

# Using config file
python -m src.n8n_mcp.server

# Using environment variables
python -m src.n8n_mcp.server --env

# Using custom config path
python -m src.n8n_mcp.server /path/to/config.json

Using with an MCP Client (e.g., Claude Desktop)

You can connect any MCP-compatible client to this server. Here are a couple of common methods:

Method 1: Connecting to the Docker Container (Recommended)

Once the Docker container is running, it exposes the MCP server on port 8080. You can connect your MCP client to it by defining a remote server.

In your MCP client's configuration (e.g., claude_desktop_config.json), add a server entry pointing to http://localhost:8080:

{
  "mcpServers": {
    "n8n-docker": {
      "url": "http://localhost:8080"
    }
  }
}

Remember to replace "n8n-docker" with the name you want to use for the tool provider.

Method 2: Running from Source (For Development)

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "n8n-local": {
      "command": "python",
      "args": [
        "-m",
        "src.n8n_mcp.server",
        "--env"
      ],
      "cwd": "/absolute/path/to/n8n-mcp-server"
    }
  }
}

Make sure you have a .env file in the project root or have the necessary environment variables exported in your shell.

Example Operations

Create a Workflow

# Ask Claude:
"Create a new n8n workflow called 'Data Sync' that syncs data between two systems"

Search Workflows

# Ask Claude:
"Find all workflows with 'email' in their name"

Activate a Workflow

# Ask Claude:
"Activate the workflow with ID 'abc123'"

📚 Available Tools

1. create_workflow

Create a new n8n workflow.

Parameters:

• name (required): Workflow name
• nodes (optional): Array of node configurations
• connections (optional): Node connections object
• active (optional): Boolean, default false
• tags (optional): Array of tag objects

2. get_workflow

Retrieve a specific workflow by ID.

Parameters:

• workflow_id (required): Workflow ID
• use_cache (optional): Boolean, default true

3. list_workflows

List workflows with optional filters.

Parameters:

• active (optional): Filter by active status
• tags (optional): Array of tag names
• limit (optional): Max results (1-100), default 20
• offset (optional): Pagination offset, default 0

4. search_workflows

Search workflows by name or tags.

Parameters:

• query (required): Search query string
• limit (optional): Max results (1-100), default 20

5. update_workflow

Update an existing workflow.

Parameters:

• workflow_id (required): Workflow ID
• name (optional): New workflow name
• nodes (optional): Updated nodes configuration
• connections (optional): Updated connections
• active (optional): Active status
• tags (optional): Updated tags

6. delete_workflow

Delete a workflow.

Parameters:

• workflow_id (required): Workflow ID

7. activate_workflow

Activate a workflow to make it run automatically.

Parameters:

• workflow_id (required): Workflow ID

8. deactivate_workflow

Deactivate a workflow to stop automatic execution.

Parameters:

• workflow_id (required): Workflow ID

9. health_check

Check n8n API connection health.

Parameters: None

🏗 Project Structure

n8n-mcp-server/
├── src/
│   └── n8n_mcp/
│       ├── __init__.py
│       ├── server.py          # Main MCP server implementation
│       ├── client.py          # n8n API client
│       ├── config.py          # Configuration management
│       └── logging_config.py  # Logging setup
├── config/
│   ├── config.json            # Main configuration
│   └── config.example.json    # Configuration template
├── tests/
│   ├── test_client.py
│   └── test_server.py
├── docs/
│   └── USAGE.md              # Detailed usage guide
├── logs/                      # Log files directory
├── requirements.txt          # Python dependencies
├── setup.py                  # Package setup
├── .gitignore
├── LICENSE
└── README.md                 # This file

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=src/n8n_mcp --cov-report=html

# Run specific test file
pytest tests/test_client.py

🔧 Development

Setup Development Environment

# Install development dependencies
pip install -r requirements.txt

# Install pre-commit hooks
pre-commit install

# Run code formatting
black src/ tests/

# Run linting
flake8 src/ tests/

# Type checking
mypy src/

Code Style

This project follows:

• PEP 8 style guide
• Black for code formatting
• isort for import sorting
• Type hints for better code quality

🐛 Troubleshooting

Common Issues

Issue: "Configuration error: Invalid n8n configuration"

• Solution: Check your n8n base URL and API key in config.json

Issue: "API health check failed"

• Solution: Verify your n8n instance is accessible and API key is valid

Issue: "Import Error: No module named 'mcp'"

• Solution: Install dependencies: pip install -r requirements.txt

Debug Mode

Enable debug logging in config.json:

{
  "logging": {
    "level": "DEBUG"
  }
}

📊 Performance Tips

1. Caching: Adjust cache_ttl based on your workflow update frequency
2. Pagination: Use limit and offset for large workflow lists
3. Retry Logic: Tune max_retries for unstable networks
4. Timeouts: Increase timeout for complex workflows

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📝 Changelog

See CHANGELOG.md for version history.

📄 License

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

🙏 Acknowledgments

• n8n for the amazing workflow automation platform
• Model Context Protocol for the MCP standard
• Anthropic for Claude and MCP inspiration

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: support@yourproject.com

🔗 Links

• n8n Documentation
• n8n API Reference
• MCP Documentation
• Project Homepage

---

Made with ❤️ for the n8n and AI automation community