N8n MCP Lite

n8n mcp lite

MCP针对现实世界的工作流程规模进行了重新设计。

如果你的n8n工作流有超过40个节点，标准MCP在结构上就不可用了。 n8n-mcp-lite仍然可行。

______________________________________________________________________

基准

在相同的工作流程上进行测量。通过OpenAI令牌化器进行令牌计数。

超过~50个节点时，标准MCP就不再具有上下文可行性。n8n mcp-lite仍然可用。

标准MCP实现在每次上下文转换时对整个工作流图进行序列化。在大型工作流中，这会产生完全超过实际上下文窗口的令牌计数，使得在一定的工作流大小以上，可靠的人工智能辅助在结构上是不可能的。

n8n mcp-lite在架构级别解决了这个问题，而不是通过压缩或摘要黑客。

______________________________________________________________________

这是给谁的

n8n用户，工作流程不断增长

• 希望人工智能帮助安全地管理、调试和扩展工作流程
• 不想理解n8n JSON内部
• 需要相信人工智能不会破坏生产

开发人员构建生产自动化

• 关心确定性序列化
• 大型工作流需要选择性上下文
• 在发生任何突变之前，需要回滚和结构保证
• 构建具有30、50、100+节点的工作流

______________________________________________________________________

快速开始

1. 为您的客户完成安装(光标 / 克劳德桌面版).
2. 问你的AI助手： *“列出我的n8n工作流。”*
3. 问： *“扫描工作流\[名称\]。”* --返回轻量级的概述，而不加载完整的JSON。
4. 问： *“关注\[节点名称\]。”* --仅加载所需的节点。
5. 进行更改。每个突变都会运行安全检查，并在接触n8n之前创建自动快照。

不需要n8n内部知识。服务器自动处理格式转换、验证和上下文管理。

______________________________________________________________________

5分钟验证测试

安装后：

1. 问： *“列出我的工作流。”*
2. 选择一个包含30多个节点的工作流。问： *“扫描它。”*
3. 注意响应中的令牌估计。
4. 将其与该工作流的原始JSON大小进行比较。
5. 问： *“关注\[一个节点名称\]。”* --看看上下文进一步下降了多少。

如果您的工作流超过50个节点，则差异将立即可见。

______________________________________________________________________

现实世界场景

大型工作流（50+节点）

标准MCP每次都会发送整个工作流程图。从规模上讲，这完全超出了上下文窗口——响应降级或失败。n8n mcp-lite只发送所需的内容，无论工作流大小如何，都能保持交互的可行性。

调试损坏的表达式

Ghost Payload附加 inputHint 每个聚焦节点显示精确的 $json 来自上游的字段名——从实际执行数据中提取。不再猜测存在哪些字段。

安全的AI重构

每个突变在接触n8n API之前都会运行一个7层安全预飞。捕获并阻止硬编码凭据、损坏的表达式、SQL注入模式和结构错误。API从不在失败检查时调用。

从糟糕的变化中恢复

每个变异在执行之前都会自动快照工作流。 rollback_workflow 精确恢复任何先前状态。每个工作流最多20个快照，自动修剪。

______________________________________________________________________

这是什么

n8n mcp-lite是一个mcp服务器，它将AI客户端（Claude、Cursor或任何兼容mcp的客户端）连接到n8n实例。它暴露了 26工具 跨越六个类别——读取、写入、激活、执行、版本控制和节点知识库——所有这些都在为人工智能交互而构建的紧凑序列化格式上运行。

服务器设计为：

• 代币有纪律 --每个工具边界处的最小上下文
• 建筑安全 --每次写入操作都会运行安全预检并创建自动快照
• 确定性的 --LiteNode格式在通话中稳定且可预测
• 模型无关 --适用于任何兼容MCP的AI客户端

______________________________________________________________________

安装

先决条件

• Node.js≥18.0.0
• 已启用API访问的n8n实例
• n8n API密钥(Settings → API → Create API Key)

克隆存储库并构建：

git clone https://github.com/LunkiBR/n8n-mcp-lite.git
cd n8n-mcp-lite
npm install
npm run build

______________________________________________________________________

光标

创建或编辑 ~/.cursor/mcp.json （全球）或 .cursor/mcp.json （每个项目）：

{
  "mcpServers": {
    "n8n-mcp-lite": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp-lite/dist/index.js"],
      "env": {
        "N8N_HOST": "https://your-n8n.example.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

保存后重新启动Cursor。MCP服务器将出现在活动工具面板中。

______________________________________________________________________

克劳德桌面版

编辑Claude Desktop配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "n8n-mcp-lite": {
      "command": "node",
      "args": ["/absolute/path/to/n8n-mcp-lite/dist/index.js"],
      "env": {
        "N8N_HOST": "https://your-n8n.example.com",
        "N8N_API_KEY": "your-api-key"
      }
    }
  }
}

重新启动克劳德桌面。服务器在启动时自动注册。

备注：不要在中使用相对路径 args.Claude Desktop在某些平台上将工作目录设置为系统根目录。始终使用绝对路径。

______________________________________________________________________

通用MCP客户端

任何支持模型上下文协议stdio传输的客户端：

{
  "command": "node",
  "args": ["/absolute/path/to/n8n-mcp-lite/dist/index.js"],
  "env": {
    "N8N_HOST": "https://your-n8n.example.com",
    "N8N_API_KEY": "your-api-key"
  }
}

服务器通过以下方式进行通信 stdin/stdout 使用标准MCP协议。没有启动HTTP服务器。

______________________________________________________________________

建筑

为什么存在

由于上下文膨胀，人工智能辅助自动化大规模中断。标准MCP不是为超过几十个节点的工作流而设计的。n8n-mcp-lite是一个为人工智能推理设计的序列化层，而不是n8n API的包装器。

核心问题

标准MCP实现在每次调用时将原始n8n工作流JSON传递给模型上下文。一个78节点的工作流产生了超过600000个原始JSON令牌，远远超出了任何实际的上下文窗口，主要包含位置元数据、默认值和与手头任务无关的结构噪声。

这不是令牌化器效率问题。这是一个序列化设计问题。

n8n-mcp-lite方法

n8n API (raw JSON)
       │
       ▼
┌─────────────────┐
│  Simplify Layer │  Strip defaults, normalize types, compress connections
└────────┬────────┘
         │  LiteNode format
         ▼
┌─────────────────┐
│  Graph Analysis │  Build adjacency graph, detect segments and branches
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Focus Engine   │  Compute boundaries, classify upstream/downstream,
│                 │  reduce non-target nodes to one-line dormant summaries
└────────┬────────┘
         │  Focused context payload
         ▼
       Model

结果：该模型准确地接收与当前任务相关的节点，为关注的节点提供完整的参数细节，并为其他所有内容提供简洁的摘要。

子系统

序列化层 (src/transform/simplify.ts) 将原始n8n JSON转换为LiteNode格式。删除所有默认值，省略空字段，规范节点类型前缀(n8n-nodes-base.httpRequest → httpRequest)，并压缩连接图。该格式在n8n版本中是稳定的。

图形分析 (src/transform/graph.ts) 从序列化工作流构建有向邻接图。检测独立分支，按路由器输出索引分段，识别入口和出口点，并对节点关系进行分类以进行焦点边界计算。

焦点引擎 (src/transform/focus.ts) 给定一组目标节点，计算焦点区域的边界，将其他每个节点分类为上游、下游或并行，并将非焦点节点减少为单行休眠摘要。通过以下方式支持节点选择、分支选择、范围选择和迭代扩展 expand_focus.

Ghost有效载荷 --当A executionId 提供给 focus_workflow，引擎读取该执行的输入数据并附加 inputHint 每个聚焦节点显示精确的 $json 来自上游的字段名称。消除了调试工作流中的表达式猜测。

安全预检 (src/security/preflight.ts) 每一个变异工具(create_workflow, update_workflow, update_nodes)在接触n8n API之前运行多层验证过程：

如果检测到任何错误级别发现，则阻止突变，响应包含结构化 errors 具有精确字段位置和修复指令的数组。从未调用n8n API。

版本存储 (src/versioning/version-store.ts) 在每次突变之前，当前工作流状态都会序列化为JSON快照 .versioning/{workflowId}/每个工作流最多保留20个快照；最老的会自动修剪。 rollback_workflow 精确还原任何快照。

审批门 (src/approval/approval-store.ts) 可选团队安全层，通过启用 N8N_REQUIRE_APPROVAL=true.启用后，变异工具将返回 pending 用a回应 approve_token 而不是立即执行。调用者必须使用令牌重新提交才能继续。所有尝试的突变都记录在仅可追加的审计日志中 .versioning/audit.log，无论审批模式状态如何。

节点知识库 (src/knowledge/) n8n节点模式、工作流模式模板、webhook有效负载模式、表达式配方和记录的节点怪癖的静态嵌入式数据库。通过询问 get_node, search_patterns, get_payload_schema, search_expressions，以及 get_n8n_knowledge.

______________________________________________________________________

功能对比

______________________________________________________________________

工具参考

阅读

写作

激活和执行

版本控制

节点知识库

审批（团队模式）

______________________________________________________________________

配置

所有配置都是通过MCP客户端配置传递的环境变量进行的。

______________________________________________________________________

设计原则

上下文是一种资源。浪费是建筑的失败。 模型应接收正确完成任务所需的最小上下文。发送更多并不是更安全，而是更吵。

决定论不是可有可无的。 LiteNode格式是可预测的。相同的工作流在每次调用时都会产生相同的序列化输出。该模型可以在不补偿方差的情况下对结构进行推理。

执行前的安全——无一例外。 没有突变达到n8n API没有通过飞行前。如果没有之前的快照，则不会执行飞行前传递突变。回滚始终可用。

该模型是一个客户端，而不是协议设计中的合作者。 服务器不假设哪个模型在MCP边界的另一侧。协议和格式在所有兼容的客户端上都是一样的。

最小的表面，最大的能力。 26个工具涵盖了完整的工作流生命周期——创建、读取、更新、删除、激活、调试、回滚和学习——没有冗余。

______________________________________________________________________

反馈与贡献

该项目正在积极优化现实世界的生产案例，而不是玩具示例。问题、错误报告、功能请求和实际结果都是受欢迎的：

• 程序错误 → 打开错误报告
• 特色创意？ → 打开功能请求
• 代币节省还是工作流程故事？ → 分享您的反馈

如果您正在运行超过50个节点的工作流，请打开一个关于您的节点数的反馈问题， scan_workflow 令牌估计和用例。来自真实工作流程的边缘案例直接塑造了接下来要构建的内容。

欢迎提供代码。在添加或修改工具时，请维护LiteNode格式合约，并确保所有变异路径都通过飞行前管道运行。

结构化问题模板位于 .github/ISSUE_TEMPLATE/.

许可证

麻省理工学院