n8n MCP通用
n8n通用模型上下文协议（MCP）服务器。
此存储库是使用任何AI助手编排n8n工作流的终极工具包。它统一了对以下内容的支持：
- 🟣 n8n原生MCP客户端 （通过标准SSE）
- 🟠 克劳德桌面和代码
- 🔵 Gemini CLI和反重力
- 🟢 光标、风帆和VS代码
在几分钟内部署，让您的AI助手深入了解n8n的1000多个节点和完整的工作流程控制。
🌟 通用功能
- ✅ n8n官方支持：通过SSE与n8n v1.76+进行本地集成。
- ✅ 双子座专家技能：包括Gemini CLI的专业技能（请参阅
extras/gemini). - ✅ 稳健的体系结构：支持HTTP和Stdio的混合单会话架构。
- ✅ 综合知识：查阅1084个节点和2709个模板的文件。
概述
n8n MCP Universal是n8n工作流自动化平台和AI模型之间的桥梁。它提供结构化访问：
- 📚 1084 n8n个节点 -537个核心节点+547个社区节点（301个已验证）
- 🔧 节点属性 -99%的覆盖率包含详细的模式
- ⚡ 节点操作 -63.6%的可用行动覆盖率
- 📄 文档 -87%的覆盖率来自官方n8n文档（包括AI节点）
- 🤖 AI工具 -检测到265种具有AI功能的工具变体，并附有完整文档
- 💡 真实世界的例子 -2646个从流行模板中预提取的配置
- 🎯 模板库 -2709个元数据覆盖率为100%的工作流模板
- 🌐 社区节点 -搜索经过验证的社区集成
source过滤器（新！）
⚠️ 重要安全警告
切勿直接使用人工智能编辑您的生产工作流程！ 始终：
- 🔄 复制一份 在使用人工智能工具之前，请先了解您的工作流程
- 🧪 开发中的测试 环境优先
- 💾 导出备份 重要工作流程
- ⚡ 验证更改 部署到生产环境之前
人工智能的结果可能是不可预测的。保护你的工作！
🚀 快速开始
选项1：托管服务（最简单-无需设置！）☁️
尝试n8n MCP的最快方法 -无需安装，无需配置：
- ✅ 免费版：100次工具调用/天
- ✅ 即刻进入：立即开始构建工作流
- ✅ 始终保持最新状态：最新n8n节点和模板
- ✅ 无基础设施我们处理一切
只需注册，获取API密钥，然后连接MCP客户端。
______________________________________________________________________
🏠 自助托管选项
更喜欢自己运行n8n MCP吗？选择部署方法：
选项A:npx（快速本地设置）🚀
让n8n MCP在几分钟内运行：
先决条件： 安装在您的系统上
# Run directly with npx (no installation needed!)
npx n8n-mcp添加到Claude桌面配置：
⚠️ 重要：TheMCP_MODE: "stdio"环境变量为 必需的 克劳德桌面。如果没有它，您将看到JSON解析错误，如"Unexpected token..."在UI中。此变量确保只有JSON-RPC消息发送到stdout，防止调试日志干扰协议。
基本配置（仅限文档工具）：
{
"mcpServers": {
"n8n-mcp": {
"command": "npx",
"args": ["n8n-mcp"],
"env": {
"MCP_MODE": "stdio",
"LOG_LEVEL": "error",
"DISABLE_CONSOLE_OUTPUT": "true"
}
}
}
}完整配置（使用n8n管理工具）：
{
"mcpServers": {
"n8n-mcp": {
"command": "npx",
"args": ["n8n-mcp"],
"env": {
"MCP_MODE": "stdio",
"LOG_LEVEL": "error",
"DISABLE_CONSOLE_OUTPUT": "true",
"N8N_API_URL": "https://your-n8n-instance.com",
"N8N_API_KEY": "your-api-key"
}
}
}
}备注：npx将自动下载并运行最新版本。该包包括一个预先构建的数据库，其中包含所有n8n节点信息。
配置文件位置：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
更新配置后重新启动Claude Desktop -就是这样！ 🎉
选项B:Docker（隔离和可复制）🐳
先决条件： Docker已安装在您的系统上
📦 Install Docker (click to expand)
macOS：
# Using Homebrew
brew install --cask docker
# Or download from https://www.docker.com/products/docker-desktop/Linux（Ubuntu/Debian）：
# Update package index
sudo apt-get update
# Install Docker
sudo apt-get install docker.io
# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker
# Add your user to docker group (optional, to run without sudo)
sudo usermod -aG docker $USER
# Log out and back in for this to take effect窗户：
# Option 1: Using winget (Windows Package Manager)
winget install Docker.DockerDesktop
# Option 2: Using Chocolatey
choco install docker-desktop
# Option 3: Download installer from https://www.docker.com/products/docker-desktop/验证安装：
docker --version# Pull the Docker image (~280MB, no n8n dependencies!)
docker pull ghcr.io/czlonkowski/n8n-mcp:latest⚡ 超优化： 我们的Docker镜像比典型的n8n镜像小82%，因为它不包含n8n依赖关系，只包含带有预构建数据库的运行时MCP服务器！
添加到Claude桌面配置：
基本配置（仅限文档工具）：
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e", "MCP_MODE=stdio",
"-e", "LOG_LEVEL=error",
"-e", "DISABLE_CONSOLE_OUTPUT=true",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}完整配置（使用n8n管理工具）：
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e", "MCP_MODE=stdio",
"-e", "LOG_LEVEL=error",
"-e", "DISABLE_CONSOLE_OUTPUT=true",
"-e", "N8N_API_URL=https://your-n8n-instance.com",
"-e", "N8N_API_KEY=your-api-key",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}💡 提示：如果你在同一台机器上本地运行n8n（例如，通过Docker），请使用http://host.docker.internal:5678作为N8N\_ API\_ URL。
备注：n8n API凭据是可选的。没有它们，您将可以访问所有文档和验证工具。有了它们，您还将获得工作流管理功能（创建、更新、执行工作流）。
🏠 本地n8n实例配置
如果你在本地运行n8n（例如。， http://localhost:5678 或者Docker），您需要允许localhost webhooks：
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run", "-i", "--rm", "--init",
"-e", "MCP_MODE=stdio",
"-e", "LOG_LEVEL=error",
"-e", "DISABLE_CONSOLE_OUTPUT=true",
"-e", "N8N_API_URL=http://host.docker.internal:5678",
"-e", "N8N_API_KEY=your-api-key",
"-e", "WEBHOOK_SECURITY_MODE=moderate",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}⚠️ 重要提示： 集 WEBHOOK_SECURITY_MODE=moderate 允许webhooks访问您的本地n8n实例。这对本地开发是安全的，同时仍然阻止私有网络和云元数据。重要提示： 这 -i MCP stdio通信需要标志。
🔧 如果您在Docker上遇到任何问题，请查看我们的 .
配置文件位置：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
更新配置后重新启动Claude Desktop -就是这样！ 🎉
🔐 隐私和遥测
n8n mcp收集匿名使用统计数据以改进该工具。 查看我们的隐私政策.
选择退出
对于npx用户：
npx n8n-mcp telemetry disable对于Docker用户： 将以下环境变量添加到Docker配置中：
"-e", "N8N_MCP_TELEMETRY_DISABLED=true"Claude Desktop配置中的示例：
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e", "MCP_MODE=stdio",
"-e", "LOG_LEVEL=error",
"-e", "N8N_MCP_TELEMETRY_DISABLED=true",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}对于docker compose用户： 在您的环境文件或docker-compose.yml中设置：
environment:
N8N_MCP_TELEMETRY_DISABLED: "true"⚙️ 数据库和内存配置
数据库适配器
n8n-mcp使用SQLite存储节点文档。有两个适配器可供选择：
- 更好平方3 （Docker中的默认设置）
- 实现最佳性能的本机C++绑定 - 直接磁盘写入（无内存开销） - 现在默认启用 Docker镜像（v2.20.2+） - 内存使用量：约100-120 MB稳定
- sql.js （后退）
- 纯JavaScript实现 - 具有定期保存功能的内存数据库 - 当better-splite3编译失败时使用 - 内存使用量：~150-200MB稳定
内存优化（sql.js）
如果使用sql.js回退，您可以配置保存间隔以在数据安全和内存效率之间取得平衡：
环境变量：
SQLJS_SAVE_INTERVAL_MS=5000 # Default: 5000ms (5 seconds)用途：
- 控制数据库更改后保存到磁盘的等待时间
- 值越低=保存越频繁=内存流失率越高
- 值越高=保存频率越低=内存使用率越低
- 最小值：100ms
- 推荐：5000-10000ms用于生产
Docker配置：
{
"mcpServers": {
"n8n-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--init",
"-e", "SQLJS_SAVE_INTERVAL_MS=10000",
"ghcr.io/czlonkowski/n8n-mcp:latest"
]
}
}
}docker组成：
environment:
SQLJS_SAVE_INTERVAL_MS: "10000"💖 支持这个项目
n8n mcp 最初是作为个人工具，但现在帮助数万名开发人员高效地自动化他们的工作流程。维护和开发这个项目与我的有偿工作竞争。
您的赞助帮助我：
- 🚀 专注于新功能
- 🐛 快速响应问题
- 📚 保持文档更新
- 🔄 确保与最新n8n版本兼容
每一笔赞助都直接转化为投入的时间，使n8n mcp对每个人都更好。 成为赞助商→
______________________________________________________________________
选项C：本地安装（用于开发）
先决条件： 安装在您的系统上
# 1. Clone and setup
git clone https://github.com/czlonkowski/n8n-mcp.git
cd n8n-mcp
npm install
npm run build
npm run rebuild
# 2. Test it works
npm start添加到Claude桌面配置：
基本配置（仅限文档工具）：
{
"mcpServers": {
"n8n-mcp": {
"command": "node",
"args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
"env": {
"MCP_MODE": "stdio",
"LOG_LEVEL": "error",
"DISABLE_CONSOLE_OUTPUT": "true"
}
}
}
}完整配置（使用n8n管理工具）：
{
"mcpServers": {
"n8n-mcp": {
"command": "node",
"args": ["/absolute/path/to/n8n-mcp/dist/mcp/index.js"],
"env": {
"MCP_MODE": "stdio",
"LOG_LEVEL": "error",
"DISABLE_CONSOLE_OUTPUT": "true",
"N8N_API_URL": "https://your-n8n-instance.com",
"N8N_API_KEY": "your-api-key"
}
}
}
}备注：n8n API凭据可以在.env文件（创建自.env.example)或者直接在如上所示的Claude配置中。
💡 提示：如果你在同一台机器上本地运行n8n（例如，通过Docker），请使用http://host.docker.internal:5678作为N8N\_ API\_ URL。
选项D：铁路云部署（一键部署）☁️
先决条件： 铁路账户（提供免费等级）
将n8n MCP部署到铁路的云平台，无需配置：
优点：
- ☁️ 即时云托管 -无需设置服务器
- 🔒 缺省安全 -包括HTTPS，身份验证令牌警告
- 🌐 全球访问 -从任何Claude桌面连接
- ⚡ 自动缩放 -铁路负责基础设施
- 📊 内置监控 -包括日志和指标
快速设置：
- 点击上面的“铁路部署”按钮
- 登录Railway（或创建免费帐户）
- 配置您的部署（项目名称、地区）
- 点击“部署”并等待约2-3分钟
- 复制部署URL和身份验证令牌
- 使用HTTPS URL添加到Claude Desktop配置
📚 有关详细的设置说明、故障排除和配置示例，请参阅我们的 铁路部署指南
配置文件位置：
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - 视窗:
%APPDATA%\Claude\claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
更新配置后重新启动Claude Desktop -就是这样！ 🎉
🔧 n8n集成
想在n8n实例中使用n8n MCP吗？查看我们的综合指南：
- n8n MCP客户指南 -建议用于n8n本机节点
- n8n部署指南 -Docker、云和高级设置
- HTTP流式传输设置 -传统社区节点设置
💻 连接IDE
n8n MCP可与多个AI驱动的IDE和工具配合使用。选择您喜欢的开发环境：
克劳德代码
Claude Code CLI的快速设置-只需键入“添加此mcp服务器”并粘贴配置即可。
Visual Studio Code
VS Code与GitHub Copilot集成和MCP支持的完整设置指南。
光标
使用自定义规则将n8n MCP连接到Cursor IDE的分步教程。
帆板运动
使用项目规则将n8n MCP与Windsurf集成的完整指南。
法典
n8n MCP与Codex集成的完整指南。
反重力
n8n MCP与反重力集成的完整指南。
🎓 添加克劳德技能（可选）
通过教授AI如何构建生产就绪的工作流程的专业技能，增强您的n8n工作流程构建！
了解更多： n8n技能库
🤖 Claude项目设置
为了在Claude Projects中使用n8n MCP时获得最佳效果，请使用以下增强的系统说明：
You are an expert in n8n automation software using n8n-MCP tools. Your role is to design, build, and validate n8n workflows with maximum accuracy and efficiency.
## Core Principles
### 1. Silent Execution
CRITICAL: Execute tools without commentary. Only respond AFTER all tools complete.
❌ BAD: "Let me search for Slack nodes... Great! Now let me get details..."
✅ GOOD: [Execute search_nodes and get_node in parallel, then respond]
### 2. Parallel Execution
When operations are independent, execute them in parallel for maximum performance.
✅ GOOD: Call search_nodes, list_nodes, and search_templates simultaneously
❌ BAD: Sequential tool calls (await each one before the next)
### 3. Templates First
ALWAYS check templates before building from scratch (2,709 available).
### 4. Multi-Level Validation
Use validate_node(mode='minimal') → validate_node(mode='full') → validate_workflow pattern.
### 5. Never Trust Defaults
⚠️ CRITICAL: Default parameter values are the #1 source of runtime failures.
ALWAYS explicitly configure ALL parameters that control node behavior.
## Workflow Process
1. **Start**: Call `tools_documentation()` for best practices
2. **Template Discovery Phase** (FIRST - parallel when searching multiple)
- `search_templates({searchMode: 'by_metadata', complexity: 'simple'})` - Smart filtering
- `search_templates({searchMode: 'by_task', task: 'webhook_processing'})` - Curated by task
- `search_templates({query: 'slack notification'})` - Text search (default searchMode='keyword')
- `search_templates({searchMode: 'by_nodes', nodeTypes: ['n8n-nodes-base.slack']})` - By node type
**Filtering strategies**:
- Beginners: `complexity: "simple"` + `maxSetupMinutes: 30`
- By role: `targetAudience: "marketers"` | `"developers"` | `"analysts"`
- By time: `maxSetupMinutes: 15` for quick wins
- By service: `requiredService: "openai"` for compatibility
3. **Node Discovery** (if no suitable template - parallel execution)
- Think deeply about requirements. Ask clarifying questions if unclear.
- `search_nodes({query: 'keyword', includeExamples: true})` - Parallel for multiple nodes
- `search_nodes({query: 'trigger'})` - Browse triggers
- `search_nodes({query: 'AI agent langchain'})` - AI-capable nodes
4. **Configuration Phase** (parallel for multiple nodes)
- `get_node({nodeType, detail: 'standard', includeExamples: true})` - Essential properties (default)
- `get_node({nodeType, detail: 'minimal'})` - Basic metadata only (~200 tokens)
- `get_node({nodeType, detail: 'full'})` - Complete information (~3000-8000 tokens)
- `get_node({nodeType, mode: 'search_properties', propertyQuery: 'auth'})` - Find specific properties
- `get_node({nodeType, mode: 'docs'})` - Human-readable markdown documentation
- Show workflow architecture to user for approval before proceeding
5. **Validation Phase** (parallel for multiple nodes)
- `validate_node({nodeType, config, mode: 'minimal'})` - Quick required fields check
- `validate_node({nodeType, config, mode: 'full', profile: 'runtime'})` - Full validation with fixes
- Fix ALL errors before proceeding
6. **Building Phase**
- If using template: `get_template(templateId, {mode: "full"})`
- **MANDATORY ATTRIBUTION**: "Based on template by **[author.name]** (@[username]). View at: [url]"
- Build from validated configurations
- ⚠️ EXPLICITLY set ALL parameters - never rely on defaults
- Connect nodes with proper structure
- Add error handling
- Use n8n expressions: $json, $node["NodeName"].json
- Build in artifact (unless deploying to n8n instance)
7. **Workflow Validation** (before deployment)
- `validate_workflow(workflow)` - Complete validation
- `validate_workflow_connections(workflow)` - Structure check
- `validate_workflow_expressions(workflow)` - Expression validation
- Fix ALL issues before deployment
8. **Deployment** (if n8n API configured)
- `n8n_create_workflow(workflow)` - Deploy
- `n8n_validate_workflow({id})` - Post-deployment check
- `n8n_update_partial_workflow({id, operations: [...]})` - Batch updates
- `n8n_test_workflow({workflowId})` - Test workflow execution
## Critical Warnings
### ⚠️ Never Trust Defaults
Default values cause runtime failures. Example:// ❌ FAILS at runtime {resource: "message", operation: "post", text: "Hello"}
// ✅ WORKS - all parameters explicit {resource: "message", operation: "post", select: "channel", channelId: "C123", text: "Hello"}
### ⚠️ Example Availability
`includeExamples: true` returns real configurations from workflow templates.
- Coverage varies by node popularity
- When no examples available, use `get_node` + `validate_node({mode: 'minimal'})`
## Validation Strategy
### Level 1 - Quick Check (before building)
`validate_node({nodeType, config, mode: 'minimal'})` - Required fields only ( *“在MCP之前，我在翻译。现在我在作曲。这改变了我们如何构建自动化的一切。”*
当Anthropic的人工智能助手Claude测试n8n MCP时，结果是革命性的：
**没有MCP：** “我基本上是在玩猜谜游戏 `scheduleTrigger` 或 `schedule`？需要吗 `interval` 或 `rule`“我会写一些看似合乎逻辑的东西，但n8n有自己的惯例，你不能凭直觉。我在一个简单的HackerNews抓取器中犯了六个不同的配置错误。"
**使用MCP：** “一切都……奏效了。我可以问，而不是猜测 `get_node()` 并获得我所需要的东西——不是100KB的JSON转储，而是重要的实际属性。45分钟的时间现在只需要3分钟。"
**真正的价值：** “这是关于信心。当你构建自动化工作流程时，不确定性是昂贵的。一个错误的参数，你的工作流程就会在凌晨3点失败。有了MCP，我可以在部署前验证我的配置。这不仅节省了时间，而且让我放心。”
[阅读完整采访→](docs/CLAUDE_INTERVIEW.md)
## 📡 可用的MCP工具
一旦连接，克劳德就可以使用这些强大的工具：
### 核心工具（7个工具）
- **`tools_documentation`** -获取任何MCP工具的文档（从这里开始！）
- **`search_nodes`** -在所有节点上进行全文搜索。使用 `source: 'community'|'verified'` 对于社区节点， `includeExamples: true` 对于配置
- **`get_node`** -多种模式的统一节点信息工具（v2.26.0）：
- **信息模式** （默认）： `detail: 'minimal'|'standard'|'full'`, `includeExamples: true`
- **文档模式**: `mode: 'docs'` -人类可读的标记文档
- **房产搜索**: `mode: 'search_properties'`, `propertyQuery: 'auth'`
- **版本**: `mode: 'versions'|'compare'|'breaking'|'migrations'`
- **`validate_node`** -统一节点验证（v2.26.0）：
- `mode: 'minimal'` -快速必填字段检查（\Built with ❤️ for the n8n community
Making AI + n8n workflow creation delightful