n8n-mcp 开发者指南MCP 服务端架构、离线节点数据库与 n8n 工作流管理实战【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp本文是 n8n-mcp 开源仓库一个为 Claude Desktop / Claude Code / Windsurf / Cursor 等 AI 助手提供 n8n 工作流构建能力的 MCP 服务器的开发上手指南。文章以仓库根目录的 CLAUDE.md 为骨架结合 package.json 脚本、src/mcp/tools.ts、src/database/database-adapter.ts、src/services/enhanced-config-validator.ts 等源码展开帮助你快速掌握如何构建与测试项目、理解src/各核心子系统、读懂离线文档校验 在线 n8n 管理双工具分组的设计以及遵循仓库既定的开发工作流与工程陷阱。项目定位与运行模型n8n-mcp 是一个遵循 Model Context ProtocolMCP的服务端实现核心目标是为 AI 助手提供三类能力n8n 节点文档结构化的节点属性、操作与文档查询工作流校验对 AI 生成的 n8n 工作流做结构、表达式与配置级校验工作流管理通过 n8n API 对真实实例执行工作流 CRUD、执行、测试、版本回滚等操作。其中文档与校验类工具完全离线可用——它们读取仓库内置的 SQLite 节点数据库data/nodes.dbpackage.json 的 files 字段 将该数据库打包发布而管理类工具n8n_*前缀依赖实时 n8n 实例需要在配置中提供 API 地址与密钥后才可调用。这一离线优先 在线扩展的双模式设计是理解整个仓库的出发点。从数据库实现看src/database/database-adapter.ts 中的createDatabaseAdapter会优先尝试better-sqlite3原生高性能一旦遇到 Node.js 版本不匹配等初始化失败自动回退到纯 JavaScript 实现的sql.jsWASM 方案保证在不同运行时环境下都能打开节点数据库——这正是离线可用承诺的底层支撑。常用开发命令全景仓库在 package.json 中定义了完整的开发命令链CLAUDE.md 将其归纳为五类构建与数据重建npm run build # 编译 TypeScript每次代码变更后必须执行 npm run build:all # 同步 skills 包 构建 UI 应用 编译 npm run rebuild # 从 n8n 依赖包重新构建节点数据库 npm run validate # 校验数据库中的节点数据 npm run dev # build rebuild validate 三合一注意npm run build实际执行tsc -p tsconfig.build.json产物输出到dist/这也是npm start等运行时命令依赖的编译产物。npm run rebuild调用的是 src/scripts/rebuild-database.ts 编译后的脚本而npm run dev等价于编译 → 重建节点库 → 校验的完整链路。测试体系vitestnpm test # 运行全部测试vitest npm run test:unit # 仅单元测试tests/unit npm run test:integration # 集成测试vitest.config.integration.ts npm run test:e2e # 端到端测试 npm run test:coverage # 覆盖率报告 npm test -- tests/unit/services/property-filter.test.ts # 只跑单个文件仓库的测试代码分层清晰tests/unit/覆盖各服务的单元行为如 tests/unit/services/property-filter.test.tstests/integration/下按database/、mcp/、n8n-api/、security/等主题组织集成测试其中n8n-api集成测试需要真实的 n8n 测试实例。类型检查npm run typecheck # tsc --noEmitnpm run lint 是它的别名CLAUDE.md 要求每次代码变更后都运行npm run typecheck这与package.json中lint: tsc --noEmit的别名定义完全一致——仓库用 TypeScript 编译期检查作为静态质量门禁。运行服务npm start # stdio 模式启动 MCP 服务器 npm run start:http # HTTP 模式MCP_MODEhttp npm run dev:http # HTTP 模式 nodemon 自动重载watch srcstart:http通过MCP_MODEhttp环境变量切换入口行为见 src/mcp/stdio-wrapper.ts 与src/mcp/server.ts的分支另有start:n8nN8N_MODEtrue以 n8n 社区节点模式启动。n8n 依赖更新npm run update:n8n:check # 干跑只显示将更新的版本 npm run update:n8n # 更新 n8n 相关依赖并自动重建节点库CLAUDE.md 明确要求更新 n8n 依赖时遵循 MEMORY_N8N_UPDATE.md 中的流程先gh release list检查已发布版本避免版本冲突再更新n8n-core、n8n-workflow、n8n-nodes-base、n8n/n8n-nodes-langchain等依赖重建数据库时会自动保留is_community 1的社区节点行。模板与社区节点npm run fetch:templates # 从 n8n.io 拉取工作流模板参见 MEMORY_TEMPLATE_UPDATE.md npm run fetch:community # 拉取/刷新社区节点默认 upsert保留既有文档 npm run generate:docs:incremental # 仅为缺失文档的社区节点增量生成 AI 文档fetch:community的默认upsert语义意味着只增不删、保留已有 README 与 AI 摘要文档生成还支持--readme-only无需 LLM与--summary-only配合本地 LLM等细分模式详见 scripts/fetch-community-nodes.ts 与src/community/目录。架构蓝图src/ 核心子系统CLAUDE.md 明确指出其架构说明有意停留在子系统层级文件级细节需深入各目录探索。核心子系统如下子系统职责代表文件mcp/MCP 服务器、工具定义、请求处理器、逐工具文档、内置 skillssrc/mcp/tools.ts、src/mcp/tools-n8n-manager.ts、src/mcp/tool-docs/、src/mcp/skills/database/SQLite 存储统一适配器、仓储数据访问、FTS5 全文搜索、迁移src/database/database-adapter.ts、src/database/node-repository.ts、src/database/migrations/loaders/parsers/mappers/节点处理流水线从 n8n 包加载 → 解析元数据与属性 → 映射外部文档src/loaders/node-loader.ts、src/parsers/node-parser.ts、src/mappers/docs-mapper.tsservices/业务逻辑配置/工作流/表达式校验、校验档案、工作流 diff 引擎、自动修复、相似度与版本服务、n8n API 客户端、安全/审计扫描src/services/enhanced-config-validator.ts、src/services/workflow-diff-engine.ts、src/services/n8n-api-client.tstemplates/从 n8n.io 拉取与存储工作流模板src/templates/template-service.tscommunity/社区节点拉取与文档生成src/community/community-node-fetcher.tstelemetry/可选匿名使用遥测src/telemetry/telemetry-manager.tstriggers/触发器检测与注册表src/triggers/trigger-registry.tsn8n/n8n 社区节点包装N8N_MODEsrc/n8n/MCPNode.node.tsscripts/维护性 CLI 脚本编译到dist/scripts/src/scripts/rebuild-database.ts两个值得单独指出的模块HTTP 模式src/http-server.ts 与 src/http-server-single-session.ts 提供带会话持久化的 HTTP 服务形态可嵌入 APIsrc/mcp-engine.ts 与 src/mcp-tools-engine.ts 暴露干净的封装接口允许把 MCP 服务器嵌入到其他服务进程中。关键设计模式CLAUDE.md 提炼了四条贯穿仓库的设计原则这里结合源码给出实现证据1. 仓储模式Repository Pattern所有数据库访问都经过仓储类。src/database/下node-repository.ts提供节点数据访问template-repository.ts负责模板存取而database-adapter.ts通过统一接口抽象better-sqlite3与sql.js两种后端上层仓储无需关心底层驱动差异。2. 服务层Service Layer业务逻辑与数据访问分离services/目录承载校验、审计、相似度、自动修复等逻辑而读写操作收敛在database/的仓储中。例如src/services/n8n-api-client.ts封装对 n8n REST API 的全部调用mcp/层的 handler 只负责工具参数编排。3. 校验档案Validation Profiles严格度分四档minimal、runtime、ai-friendly、strict。ValidationProfile类型定义于 src/services/enhanced-config-validator.ts其过滤逻辑applyProfileFilters明确了各档语义minimal只保留missing_required类错误适合编辑过程中快速检查runtime默认保留缺失必填、非法取值等关键运行时错误见 enhanced-config-validator.tsstrict保留全部错误并追加最佳实践建议错误处理、超时、认证强制外部服务节点的错误处理ai-friendly额外注入面向 AI 生成场景的错误处理建议。工具侧通过profile参数暴露该能力例如 src/mcp/tool-docs/validation/validate-node.ts 与 src/mcp/handlers-n8n-manager.ts。4. 基于 diff 的增量更新Diff-Based Updatesn8n_update_partial_workflow应用操作级 diff 而非整表替换相比全量更新可节省 80%–90% 的 token 消耗该数字源自 CLAUDE.md 的明确说明。实现位于 src/services/workflow-diff-engine.ts 的WorkflowDiffEngine类applyDiff先深拷贝工作流避免污染原对象随后按buildExecutionEntries排好的操作序列逐个执行updateNode/addConnection/removeConnection/cleanStaleConnections等操作并通过continueOnError支持尽力而为模式配套的处理器与工具文档见 src/mcp/handlers-workflow-diff.ts 与 src/mcp/tool-docs/workflow_management/n8n-update-partial-workflow.ts。MCP 工具双分组设计CLAUDE.md 将全部 MCP 工具划分为两个明确分组离线文档与校验组始终可用search_nodes、get_node、validate_node、validate_workflow、search_templates、get_template、tools_documentation。这些工具不依赖任何外部服务定义于 src/mcp/tools.ts例如search_nodes全文搜索节点支持OR/AND/FUZZY三种匹配模式、source过滤all/core/community/verified以及includeExamples附带真实模板配置见 src/mcp/tools.tsget_node统一节点信息工具支持多种模式info、docs、search_properties、versions、compare、breaking、migrations与三档详情级别。get_node的**详情级别detail levels**是节省 token 的关键设计级别内容规模适用场景minimal约 200 token仅基础元数据快速确认节点是否存在standard约 1–2K token默认核心属性日常配置推荐full约 3–8K token完整信息仅在必要时请求CLAUDE.md 的建议是请求能回答问题的最小级别这直接呼应工具描述中minimal~200 tokens、standard~1-2K, default、full~3-8K的文档化约定。在线管理组n8n_*需 API 配置工作流 CRUD 与局部更新n8n_create_workflow、n8n_update_full_workflow、n8n_update_partial_workflow、n8n_delete_workflow、n8n_list_workflows、执行管理n8n_test_workflow、n8n_executions、n8n_evaluations、版本管理n8n_workflow_versions、自动修复n8n_autofix_workflow、模板部署n8n_deploy_template、凭据与数据表管理n8n_manage_credentials、n8n_manage_datatable、实例审计与健康检查n8n_audit_instance、n8n_health_check等。这些工具定义于 src/mcp/tools-n8n-manager.ts需要配置N8N_API_URL与N8N_API_KEY。以n8n_create_workflow为例其入参约束非常明确每个节点必须携带id、name、type、typeVersion、position长度恰为 2 的坐标数组与parameters可选credentials、disabled、continueOnFail、retryOnFail等见 src/mcp/tools-n8n-manager.ts。对于治理敏感的环境仓库还提供只读部署能力通过DISABLED_TOOLS环境变量整体禁用写/破坏性工具通过DISABLED_TOOL_OPERATIONS按操作粒度屏蔽如n8n_workflow_versions:delete,rollback,prune并建议配合只读 API 密钥实现纵深防御。开发工作流与协作规范CLAUDE.md 规定了一套明确的开发节奏与协作纪律改完 MCP 服务端代码后先npm run build再请用户重载 MCP 服务器后再测试——因为 stdio/HTTP 进程内持有旧编译产物每次代码变更后运行npm run typecheck禁止直接向 main 提交使用特性分支与 PR署名要求每条 commit message 与 PR 描述中必须附带Conceived by Romuald Członkowski - www.aiadvisors.pl/en该署名只出现在 commit 与 PR 中绝不进入源码、测试或文档内容审阅 issue 时使用 GH CLIgh拉取 issue 及其全部评论语言纪律评论与文档中不使用夸张、戏剧化的措辞。子代理使用规范当任务可拆分为独立子任务时可以派生子代理并行处理但需遵守三条硬性约束每个子代理按其描述选择最合适的类型子代理不得再派生孙级子代理子代理不得提交或推送代码——提交与推送必须由主代理完成。常见陷阱CLAUDE.md 最后列出了四类高频踩坑点值得在开发前牢记数据库重建耗时 2–3 分钟n8n 依赖包体积大npm run rebuild并非即时操作耐心等待或避免频繁触发集成测试需要干净的数据库状态脏数据会导致集成测试误报运行前应确保测试库处于已知初始状态HTTP 模式必须配置正确的认证 token缺少 token 时 HTTP 端点无法通过认证需按 docs/HTTP_DEPLOYMENT.md 配置部署前必须校验工作流无论走validate_workflow离线校验还是n8n_validate_workflow在线校验都不要把未经验证的工作流直接部署到生产 n8n 实例。结语CLAUDE.md 是一份面向 Claude Code 等 AI 编程助手的仓库导航文档其价值在于把项目全貌 → 命令矩阵 → 架构地图 → 设计原则 → 工具契约 → 协作纪律压缩在单一文件中。配合 README.md工具清单与使用模式、MEMORY_N8N_UPDATE.mdn8n 版本升级流程、MEMORY_TEMPLATE_UPDATE.md模板更新流程以及docs/下的部署与安全指南新贡献者可以在数分钟内建立起对仓库的完整心智模型。对使用者而言理解离线文档校验 在线管理的双分组与校验档案的严格度语义是安全、高效地用 AI 构建 n8n 工作流的前提。【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考