# n8n Monitoring MCP Server

**Specialized MCP server for n8n workflow monitoring with KPI analysis**

Provides Claude AI assistants with 3 focused monitoring tools for n8n workflow execution analysis. Deployed on Cloudflare Workers for global edge performance.

## 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

## Quick Start

### Prerequisites

- Node.js 18+ and npm
- Cloudflare account (free tier works)
- n8n instance with API access
- n8n API key ([create one](https://docs.n8n.io/api/authentication/))

### Installation

```bash
# 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

```bash
# 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

```bash
# Deploy to production
npm run deploy

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

## Tool Reference

### 1. n8n_get_active_workflows

List all active workflows in your n8n instance.

**Parameters**: None

**Example Request**:
```json
{
  "method": "tools/call",
  "params": {
    "name": "n8n_get_active_workflows",
    "arguments": {}
  }
}
```

**Example Response**:
```json
[
  {
    "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

**Example Request**:
```json
{
  "method": "tools/call",
  "params": {
    "name": "n8n_get_workflow_executions",
    "arguments": {
      "limit": 50
    }
  }
}
```

**Example Response**:
```json
{
  "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

**Example Request**:
```json
{
  "method": "tools/call",
  "params": {
    "name": "n8n_get_execution_details",
    "arguments": {
      "limit": 10,
      "workflowId": "abc123"
    }
  }
}
```

**Example Response**:
```json
{
  "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"
    }
  ]
}
```

## Claude Desktop Integration

Add to your `claude_desktop_config.json`:

```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"

## 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

```bash
# Run type checking
npm run typecheck

# View live logs
npm run tail

# Test locally
npm run dev
```

## Key Differences from n8n-mcp-workers

| Aspect | n8n-mcp-workers | n8n-monitoring-mcp |
|--------|-----------------|-------------------|
| **Purpose** | General n8n automation | Workflow monitoring |
| **Tools** | 32 tools (full API) | 3 tools (monitoring) |
| **Logic** | Simple API forwarding | Custom KPI processing |
| **Use Case** | Any n8n operation | Claude AI monitoring assistant |
| **Response** | Raw API data | Processed metrics + alerts |

## Contributing

Contributions welcome! Please open an issue or PR.

## License

MIT License - see [LICENSE](LICENSE) file

## Credits

- Based on [n8n-mcp-workers](https://github.com/YOUR_USERNAME/n8n-mcp-workers)
- Ported from n8n workflow (ID: f8exh14YagxEj1To)
- Built with [Model Context Protocol](https://modelcontextprotocol.io/)

## Support

- Issues: [GitHub Issues](https://github.com/YOUR_USERNAME/n8n-monitoring-mcp/issues)
- n8n Docs: [docs.n8n.io](https://docs.n8n.io)
- MCP Docs: [modelcontextprotocol.io](https://modelcontextprotocol.io)