n8n MCP Bridge - Model Context Protocol for AI Workflow Automation

Bridge between n8n workflow automation and Model Context Protocol (MCP) servers, enabling AI models to interact with 2000+ Apify tools through standardized protocols.

What is MCP?

The Model Context Protocol (MCP) is a standard that allows AI models (like Claude, GPT, etc.) to interact with external tools and data sources. This bridge implements MCP to connect:

• n8n workflows → MCP protocol → Apify Actors
• AI assistants → MCP tools → Web scrapers & automation

Key Features

Feature	Description
MCP Protocol Support	Full implementation of Model Context Protocol
Session Management	Support for 100+ concurrent MCP sessions
Data Transformation	Automatic conversion between n8n and MCP formats
2000+ Tools	Access to entire Apify Actor ecosystem
Retry Mechanisms	Comprehensive error handling with automatic retries
n8n Compatible	Works with n8n HTTP Request nodes

Target Audience

• Workflow Automation Specialists: Enhance n8n with AI-driven decision making
• AI Developers: Connect LLMs to real-world data via MCP
• DevOps Engineers: Integrate AI capabilities into automation pipelines
• Non-Technical Users: Access AI-powered web scraping without coding

Quick Start

1. Start the Actor in Standby Mode

Run this Actor to get your MCP endpoint URL:

https://n8n-apify-bridge.apify.actor

2. Connect via MCP Protocol

Create a session:

curl -X POST https://[your-url]/mcp/session \
  -H "Content-Type: application/json"

List available tools:

curl -X POST https://[your-url]/mcp/tools/list \
  -H "Content-Type: application/json"

Call a tool:

curl -X POST https://[your-url]/mcp/tools/call \
  -H "Content-Type: application/json" \
  -d '{
    "name": "execute_actor",
    "arguments": {
      "actorId": "apify/web-scraper",
      "input": {"startUrls": [{"url": "https://example.com"}]}
    }
  }'

MCP Protocol Endpoints

GET /mcp

Get MCP server info and available capabilities.

POST /mcp/session

Create a new MCP session. Returns session ID for subsequent requests.

Response:

{
  "success": true,
  "sessionId": "uuid-here",
  "data": {
    "expiresIn": 3600,
    "message": "MCP session created"
  }
}

POST /mcp/tools/list

List all available MCP tools.

Response:

{
  "success": true,
  "data": {
    "tools": [
      {
        "name": "search_actors",
        "description": "Search the Apify Store for Actors",
        "inputSchema": { ... }
      },
      {
        "name": "execute_actor",
        "description": "Execute an Apify Actor with given input",
        "inputSchema": { ... }
      }
    ]
  }
}

POST /mcp/tools/call

Execute an MCP tool.

Request:

{
  "name": "tool_name",
  "arguments": { ... }
}

Available MCP Tools

Tool	Description
search_actors	Search Apify Store for scrapers and tools
execute_actor	Run any Apify Actor with custom input
get_actor_info	Get detailed Actor information
list_loaded_actors	List pre-loaded Actors
add_actor	Pre-load an Actor for faster execution
get_run_status	Check status of a running Actor
transform_n8n_data	Convert n8n workflow data to MCP format

n8n Integration

Using HTTP Request Node

{
  "method": "POST",
  "url": "https://[your-url]/mcp/tools/call",
  "headers": {
    "Content-Type": "application/json",
    "X-MCP-Session": "{{$json.sessionId}}"
  },
  "body": {
    "name": "execute_actor",
    "arguments": {
      "actorId": "apify/google-maps-scraper",
      "input": {
        "searchStringsArray": ["restaurants in NYC"],
        "maxCrawledPlaces": 100
      }
    }
  }
}

Data Transformation

Transform n8n workflow data to MCP format:

{
  "name": "transform_n8n_data",
  "arguments": {
    "workflowData": {
      "workflowId": "workflow-123",
      "executionId": "exec-456",
      "nodeName": "Scrape Data",
      "inputData": {
        "url": "https://example.com",
        "searchQuery": "products"
      }
    },
    "targetActorId": "apify/web-scraper"
  }
}

Response:

{
  "success": true,
  "data": {
    "transformed": {
      "actorId": "apify/web-scraper",
      "input": {
        "startUrls": [{"url": "https://example.com"}],
        "queries": ["products"]
      },
      "metadata": {
        "source": "n8n",
        "workflowId": "workflow-123",
        "mcpVersion": "1.0.0"
      }
    }
  }
}

Legacy n8n Endpoints

For backwards compatibility with existing n8n workflows:

Endpoint	Method	Description
/health	GET	Health check
/actors	GET	List loaded Actors
/search	POST	Search Apify Store
/execute	POST	Execute an Actor
/transform	POST	Transform n8n data
/runs	GET	List active runs
/sessions	GET	View session info

Configuration

Parameter	Default	Description
maxSessions	100	Max concurrent MCP sessions
sessionTimeout	3600	Session timeout in seconds
defaultActors	[]	Pre-load Actors on startup
enableDynamicDiscovery	true	Auto-discover Actors
maxConcurrentRuns	5	Max parallel Actor runs
defaultTimeout	300	Default execution timeout
webhookSecret	-	Secure your endpoint

Session Management

Sessions allow:

• Client identification for logging and debugging
• Activity tracking for timeout management
• Concurrent support for multiple AI clients

Include session ID in requests:

X-MCP-Session: your-session-id

Error Handling

The bridge includes:

• Automatic retries for transient errors
• Exponential backoff for rate limits
• Detailed error messages in responses
• Timeout handling for long-running operations

Use Cases

1. AI-Powered Lead Generation

AI Assistant → MCP → search_actors("lead generation")
            → MCP → execute_actor("apify/google-maps-scraper")
            → Returns business data to AI

2. Automated Research

n8n Trigger → Transform Data → MCP Tools → Execute Scrapers → Process Results

3. Real-Time Data for LLMs

User Question → AI Model → MCP Bridge → Web Scraper → Fresh Data → AI Response

Security

• Webhook Secret: Protect endpoints with X-Webhook-Secret header
• Session Isolation: Each client gets isolated session
• Token Security: Apify tokens stored as secrets, never exposed

Cost Estimation

Component	Cost
Standby Mode (256MB)	~$0.02/hour
Actor Execution	Varies by Actor
MCP Sessions	Free

Support

• Apify Docs: docs.apify.com
• MCP Specification: modelcontextprotocol.io
• n8n Docs: docs.n8n.io

License

MIT License - free for commercial and personal use.

---

Built for the Apify $1M Challenge