n8n-monitoring-mcp

🚀 n8n监控MCP服务器

专门用于n8n工作流监控并进行KPI分析的MCP服务器。为Claude AI助手提供3种专注于n8n工作流执行分析的监控工具。部署在Cloudflare Workers上，以实现全球边缘性能。

🚀 快速开始

前提条件

• Node.js 18+ 和 npm
• Cloudflare账户（免费套餐即可）
• 具有API访问权限的n8n实例
• n8n API密钥（创建一个）

安装

# 克隆仓库
git clone https://github.com/YOUR_USERNAME/n8n-monitoring-mcp.git
cd n8n-monitoring-mcp

# 安装依赖
npm install

# 登录Cloudflare
npx wrangler login

本地开发

# 启动本地开发服务器
npm run dev

# 使用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"}'

部署到Cloudflare Workers

# 部署到生产环境
npm run deploy

# 获取你的Worker URL
# https://n8n-monitoring-mcp.YOUR_SUBDOMAIN.workers.dev

✨ 主要特性

• 3种监控工具：
  • n8n_get_active_workflows - 列出所有活动工作流
  • n8n_get_workflow_executions - 获取执行历史并进行全面的KPI分析
  • n8n_get_execution_details - 获取包含错误消息的详细失败信息
• 多租户支持：通过请求头（X-N8N-URL，X-N8N-API-KEY）使用不同的n8n实例
• 全面的KPI分析：
  • 执行摘要（总数、成功数、失败数、失败率）
  • 执行模式分布（手动、触发、Webhook等）
  • 每个工作流的指标和失败率
  • 时序分析（平均/最大/最小执行时间）
  • 近期失败分析
  • 高失败率自动警报
• 速率限制：每个租户每分钟100个请求
• 无服务器和全球部署：部署在Cloudflare Workers上，全球低延迟

💻 使用示例

工具参考

1. n8n_get_active_workflows

列出n8n实例中的所有活动工作流。 参数：无 示例请求：

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

示例响应：

[
  {
    "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

获取工作流执行历史并进行全面的KPI分析。 参数：

• limit（数字，可选）：要检索的最大执行次数（默认：100）
• workflowId（字符串，可选）：按特定工作流ID过滤 示例请求：

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

示例响应：

{
  "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": [
      "⚡ 中等失败率：16%的执行失败"
    ]
  }
}

3. n8n_get_execution_details

获取失败执行的详细信息，包括错误消息。 参数：

• limit（数字，可选）：要检索的最大失败执行次数（默认：20）
• workflowId（字符串，可选）：按特定工作流ID过滤 示例请求：

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

示例响应：

{
  "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桌面集成

将以下内容添加到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"
      }
    }
  }
}

重启Claude桌面并尝试以下提示：

• "列出所有活动的n8n工作流"
• "显示最近50次执行的工作流执行KPI"
• "获取最近失败的工作流执行的详细信息"

🔧 技术细节

速率限制

• 默认值：每个租户每分钟100个请求
• 租户ID：基于X-N8N-URL和X-N8N-API-KEY的组合
• 响应头：
  • X-RateLimit-Remaining：当前窗口中剩余的请求数
  • X-RateLimit-Reset：速率限制重置前的秒数
• 速率限制超出：返回HTTP 429响应

架构

┌─────────────────────────┐
│  客户端 (Claude桌面)    │
│  + 请求头:              │
│    X-N8N-URL           │
│    X-N8N-API-KEY       │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐
│  Cloudflare Worker      │
│  - 速率限制             │
│  - 多租户路由           │
│  - KPI处理              │
└───────────┬─────────────┘
            │
    ┌───────┴───────┐
    ▼               ▼
┌─────────┐   ┌─────────┐
│ 租户1   │   │ 租户2   │
│ n8n-no1 │   │ n8n-no2 │
└─────────┘   └─────────┘

开发

# 运行类型检查
npm run typecheck

# 查看实时日志
npm run tail

# 本地测试
npm run dev

与n8n-mcp-workers的主要区别

| 方面 | n8n-mcp-workers | n8n-monitoring-mcp | |------|-----------------|-------------------| | 目的 | 通用n8n自动化 | 工作流监控 | | 工具 | 32个工具（完整API） | 3个工具（监控） | | 逻辑 | 简单的API转发 | 自定义KPI处理 | | 用例 | 任何n8n操作 | Claude AI监控助手 | | 响应 | 原始API数据 | 处理后的指标 + 警报 |

📄 许可证

本项目采用MIT许可证，请参阅LICENSE文件。

致谢

• 基于 n8n-mcp-workers
• 从n8n工作流（ID: f8exh14YagxEj1To）移植
• 使用 Model Context Protocol 构建

支持

• 问题反馈：GitHub Issues
• n8n文档：docs.n8n.io
• MCP文档：modelcontextprotocol.io

贡献

欢迎贡献代码！请提交问题或拉取请求。