n8n-mcp-bridge

n8n-mcp-bridge

A lightweight bridge service that connects n8n workflows to Model Context Protocol (MCP) servers. This enables AI agents in n8n to seamlessly leverage specialized tools from MCP servers without requiring self-hosting of n8n.

What this service does

The n8n-mcp-bridge provides three core functionalities:

1. List Available MCP Servers: Returns a list of all configured MCP servers with their descriptions, allowing an AI agent in n8n to discover which specialized tools are available.

2. Discover Tools from an MCP Server: Queries a specific MCP server to list all available tools and their schemas, following the MCP protocol specification.

3. Execute Tool Calls: Allows executing specific tools on an MCP server and returning the results, making external functionality available to n8n workflows.

Project Structure

/n8n-mcp-bridge/
├── main.py                  # Main application file containing all functionality
├── test_api.py              # Test script for API endpoints
├── config/                  # Configuration files
│   └── servers.json         # Server configurations
├── logs/                    # Log directory (generated at runtime)
├── requirements.txt         # Python dependencies
└── README.md                # Documentation

How it works

This service:

1. Spawns Local MCP Servers: Automatically downloads and runs Node.js-based MCP servers locally using the configurations defined in config/servers.json.

2. Translates HTTP to MCP Protocol: Converts standard HTTP requests from n8n into the proper MCP protocol format.

3. Manages Server Lifecycle: Handles starting, monitoring, and gracefully shutting down MCP server processes.

4. Secures Access: Provides API key authentication to ensure only authorized clients can access the service.

Pre-configured MCP Servers

This service comes pre-configured with the following MCP servers:

1. Todoist (@abhiz123/todoist-mcp-server): Interact with Todoist tasks and projects
2. Memory (@modelcontextprotocol/server-memory): Store and retrieve information in a persistent memory store
3. Slack (@modelcontextprotocol/server-slack): Send and manage messages in Slack
4. Brave Search (@modelcontextprotocol/server-brave-search): Perform web searches using Brave Search

Configuration

MCP Server Configuration

MCP servers are configured in the config/servers.json file with the following structure:

{
  "mcpServers": {
    "server-id": {
      "command": "npx",
      "args": ["@package/name"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Environment Variables

Required environment variables are stored in the .env file:

X_API_KEY=your-service-api-key
ALLOWED_ORIGINS=https://your-n8n-instance.example.com,http://localhost:5678
BRAVE_API_KEY=your-brave-search-api-key
SLACK_BOT_TOKEN=your-slack-bot-token
SLACK_TEAM_ID=your-slack-team-id
TODOIST_API_TOKEN=your-todoist-api-token

• X_API_KEY: Authentication key for accessing this service
• ALLOWED_ORIGINS: Comma-separated list of domains allowed to make cross-origin requests to this service (required when deployed to production with n8n)
• BRAVE_API_KEY: API key for Brave Search MCP server
• SLACK_BOT_TOKEN & SLACK_TEAM_ID: Credentials for Slack MCP server
• TODOIST_API_TOKEN: API token for Todoist MCP server

API Endpoints

Health Check

GET /health

Returns the health status of the service and information about configured servers.

List All MCP Servers

GET /servers

Returns a list of all configured MCP servers with their status and metadata.

Discover Tools from an MCP Server

GET /server/{server_id}/tools

Returns a list of all tools available from the specified MCP server, including their schemas.

Call an MCP Server

POST /call/{server_id}

Sends a full MCP protocol request to the specified server.

Make a Tool Call

POST /tool-call/{server_id}

Simplified endpoint to execute a single tool call on the specified MCP server.

Deployment on Render

1. Create a new Web Service

1. Go to the Render dashboard and click "New" > "Web Service"
2. Connect your GitHub repository
3. Choose a name for your service
4. Select "Python 3" as the runtime
5. Set the build command: pip install -r requirements.txt
6. Set the start command: python main.py

2. Set Environment Variables

Add the following environment variables:

• X_API_KEY: Your secure API key for authentication
• NODE_VERSION: 16 or higher (to ensure Node.js is available)
• NPM_CONFIG_PRODUCTION: false (to ensure dev dependencies are installed)

3. Add Service-Specific API Keys

Add the necessary API keys for the MCP servers you want to use:

• BRAVE_API_KEY: For Brave Search
• SLACK_BOT_TOKEN and SLACK_TEAM_ID: For Slack integration
• TODOIST_API_TOKEN: For Todoist integration

Using with n8n

1. Test the service is running

Send a GET request to /health to verify the service is running.

2. List available MCP servers

Send a GET request to /servers with your API key in the X-API-Key header.

3. Discover tools from a server

Send a GET request to /server/{server_id}/tools with your API key in the X-API-Key header.

4. Make tool calls

In your n8n workflow, add an HTTP Request node with:

• Method: POST
• URL: https://your-render-service.onrender.com/tool-call/{server_id}
• Headers:
  • X-API-Key: your-api-key
  • Content-Type: application/json
• Body:

  {
    "tool_name": "example_tool",
    "tool_args": {
      "arg1": "value1"
    },
    "tool_call_id": "unique-id"
  }
  

Development

Setting up the development environment

1. Clone the repository
2. Create a virtual environment: python -m venv venv
3. Activate the virtual environment: source venv/bin/activate (Linux/Mac) or venv\Scripts\activate (Windows)
4. Install dependencies: pip install -r requirements.txt
5. Create a .env file with the necessary API keys
6. Run the service: python main.py