n8n-mcp-server

MrBozkay/n8n-mcp-server

3.2

If you are the rightful owner of n8n-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The n8n MCP Server is a professional Model Context Protocol server designed to manage n8n workflows programmatically, enabling seamless integration with AI assistants like Claude and GPT.

Tools
9
Resources
0
Prompts
0

n8n MCP Server 🚀

Python 3.8+ MCP License: MIT

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 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 for version history.

📄 License

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

🙏 Acknowledgments

📞 Support

🔗 Links

Made with ❤️ for the n8n and AI automation community