N8n Monitoring MCP

🚀 n8n Monitoring MCP Server

A specialized MCP server for n8n workflow monitoring with KPI analysis, providing Claude AI assistants with 3 focused monitoring tools for n8n workflow execution analysis. Deployed on Cloudflare Workers for global edge performance.

🚀 Quick Start

Prerequisites

• Node.js 18+ and npm
• Cloudflare account (free tier works)
• n8n instance with API access
• n8n API key (create one)

Installation

# Clone repository
git clone https://github.com/YOUR_USERNAME/n8n-monitoring-mcp.git
cd n8n-monitoring-mcp

# Install dependencies
npm install

# Login to Cloudflare
npx wrangler login

Local Development

# Start local dev server
npm run dev

# Test with curl
curl -X POST http://localhost:8787 \
  -H "Content-Type: application/json" \
  -H "X-N8N-URL: https://your-n8n-instance.com" \
  -H "X-N8N-API-KEY: your_api_key" \
  -d '{"method":"tools/list"}'

Deploy to Cloudflare Workers

# Deploy to production
npm run deploy

# Get your Worker URL
# https://n8n-monitoring-mcp.YOUR_SUBDOMAIN.workers.dev

✨ Features

• 3 Monitoring Tools:
  • n8n_get_active_workflows - List all active workflows
  • n8n_get_workflow_executions - Get execution history with comprehensive KPI analysis
  • n8n_get_execution_details - Get detailed failure information with error messages
• Multi-tenant Support: Use different n8n instances via request headers (X-N8N-URL, X-N8N-API-KEY)
• Comprehensive KPI Analysis:
  • Execution summary (total, success, failed, failure rate)
  • Execution modes distribution (manual, trigger, webhook, etc.)
  • Per-workflow metrics and failure rates
  • Timing analysis (avg/max/min execution time)
  • Recent failure analysis
  • Automated alerts for high failure rates
• Rate Limiting: 100 requests/minute per tenant
• Serverless & Global: Deployed on Cloudflare Workers for low latency worldwide

💻 Usage Examples

Basic Usage

1. n8n_get_active_workflows

List all active workflows in your n8n instance. Parameters: None

{
  "method": "tools/call",
  "params": {
    "name": "n8n_get_active_workflows",
    "arguments": {}
  }
}

Example Response:

[
  {
    "id": "f8exh14YagxEj1To",
    "name": "Workflow Execution Audit",
    "active": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-01-20T14:22:00.000Z"
  }
]

2. n8n_get_workflow_executions

Get workflow execution history with comprehensive KPI analysis. Parameters:

• limit (number, optional): Maximum executions to retrieve (default: 100)
• workflowId (string, optional): Filter by specific workflow ID

{
  "method": "tools/call",
  "params": {
    "name": "n8n_get_workflow_executions",
    "arguments": {
      "limit": 50
    }
  }
}

Example Response:

{
  "executionCount": 50,
  "kpis": {
    "summary": {
      "total": 50,
      "success": 42,
      "failed": 8,
      "waiting": 0,
      "running": 0,
      "failureRate": 16.0
    },
    "modes": {
      "trigger": 35,
      "webhook": 10,
      "manual": 5
    },
    "workflowMetrics": [
      {
        "workflowId": "abc123",
        "workflowName": "Data Sync Workflow",
        "total": 25,
        "success": 20,
        "failed": 5,
        "failureRate": 20.0
      }
    ],
    "timeMetrics": {
      "avgExecutionTime": 3500,
      "maxExecutionTime": 12000,
      "minExecutionTime": 500
    },
    "failureAnalysis": {
      "recentFailures": [...],
      "workflowsWithFailures": ["abc123", "def456"],
      "totalFailedWorkflows": 2
    },
    "alerts": [
      "⚡ Moderate failure rate: 16% of executions failed"
    ]
  }
}

3. n8n_get_execution_details

Get detailed information about failed executions, including error messages. Parameters:

• limit (number, optional): Maximum failed executions to retrieve (default: 20)
• workflowId (string, optional): Filter by specific workflow ID

{
  "method": "tools/call",
  "params": {
    "name": "n8n_get_execution_details",
    "arguments": {
      "limit": 10,
      "workflowId": "abc123"
    }
  }
}

Example Response:

{
  "failedExecutionCount": 5,
  "failures": [
    {
      "executionId": "exec123",
      "workflowId": "abc123",
      "workflowName": "Data Sync Workflow",
      "mode": "trigger",
      "startedAt": "2025-01-26T10:30:00.000Z",
      "errorMessage": "Connection timeout",
      "errorDescription": "Failed to connect to external API after 30 seconds",
      "lastNodeExecuted": "HTTP Request"
    }
  ]
}

Advanced Usage

Claude Desktop Integration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "n8n-monitoring": {
      "url": "https://n8n-monitoring-mcp.YOUR_SUBDOMAIN.workers.dev",
      "transport": {
        "type": "http"
      },
      "headers": {
        "X-N8N-URL": "https://your-n8n-instance.com",
        "X-N8N-API-KEY": "your_n8n_api_key"
      }
    }
  }
}

Restart Claude Desktop and try these prompts:

• "List all active n8n workflows"
• "Show me workflow execution KPIs for the last 50 executions"
• "Get details of recent failed workflow executions"

📚 Documentation

Rate Limiting

• Default: 100 requests per minute per tenant
• Tenant ID: Based on combination of X-N8N-URL and X-N8N-API-KEY
• Response Headers:
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Seconds until rate limit resets
• Rate Limit Exceeded: HTTP 429 response

Architecture

┌─────────────────────────┐
│  Client (Claude Desktop)│
│  + Request Headers:     │
│    X-N8N-URL           │
│    X-N8N-API-KEY       │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│  Cloudflare Worker      │
│  - Rate limiting        │
│  - Multi-tenant routing │
│  - KPI processing       │
└───────────┬─────────────┘
            │
    ┌───────┴───────┐
    ▼               ▼
┌─────────┐   ┌─────────┐
│ Tenant 1│   │ Tenant 2│
│ n8n-no1 │   │ n8n-no2 │
└─────────┘   └─────────┘

Development

# Run type checking
npm run typecheck

# View live logs
npm run tail

# Test locally
npm run dev

Key Differences from n8n-mcp-workers

🤝 Contributing

Contributions welcome! Please open an issue or PR.

📄 License

MIT License - see LICENSE file

👏 Credits

• Based on n8n-mcp-workers
• Ported from n8n workflow (ID: f8exh14YagxEj1To)
• Built with Model Context Protocol

🛠️ Support

• Issues: GitHub Issues
• n8n Docs: docs.n8n.io
• MCP Docs: modelcontextprotocol.io