N8n MCP Demo

n8n-MCP 集成演示

使用Docker容器化技术，展示一个跨平台的n8n工作流自动化与模型上下文协议（MCP）集成的演示。

](https://www.docker.com/)     ](https://github.com/tysoncung/n8n-mcp-demo/stargazers) ](https://github.com/tysoncung/n8n-mcp-demo/network/members) ](https://github.com/tysoncung/n8n-mcp-demo/issues) ](https://github.com/tysoncung/n8n-mcp-demo/commits/master) ](https://docs.docker.com/compose/)  

📋 概述

此仓库包含一个完整的、可投入生产的演示，展示了如何将n8n（工作流自动化平台）与MCP（模型上下文协议）集成。整个系统栈在Docker容器中运行，确保在Windows和macOS环境下的行为一致性。

主要特点

• ✅ 跨平台兼容性 - 在Windows和Mac上行为一致
• ✅ 容器化部署 - 无需依赖安装
• ✅ 预配置的工作流 - 立即可用的n8n-MCP集成示例
• ✅ 模拟的MCP服务器 - 展示协议集成模式
• ✅ 翻译为中文是：✓（对号/正确） 可投入生产的架构 - 遵循基础设施最佳实践
• ✅（对号，表示正确、确认或完成） 全面的文件记录 - 安装、故障排除和架构指南

🏗️ 建筑学

┌─────────────────────────────────────────────────────────────┐
│                     Docker Network                          │
│                                                             │
│  ┌──────────────┐                    ┌──────────────────┐   │
│  │              │                    │                  │   │
│  │   n8n        │◄──────HTTP────────►│   MCP Server     │   │
│  │   (Port 5678)│                    │   (Port 8080)    │   │
│  │              │                    │                  │   │
│  └──────┬───────┘                    └──────────────────┘   │
│         │                                                   │
│         │                                                   │
└─────────┼───────────────────────────────────────────────────┘
          │
          │ Webhook
          ▼
    External Client
   (curl, Postman, etc.)

组件

1. n8n 容器带有预加载MCP集成工作流的工作流自动化引擎
2. MCP 服务器容器基于FastAPI的模型上下文协议端点模拟
3. Docker 网络私有网络，实现容器间安全通信
4. 持久卷存储n8n数据、工作流和配置

🚀 快速入门

先决条件

• Git 用于克隆仓库
• 8GB内存 最低要求（建议16GB）
• 可用端口5678（n8n），8080（MCP服务器）

安装

1. 克隆仓库

   git clone https://github.com/yourusername/n8n-mcp-demo.git
   cd n8n-mcp-demo

1. 配置环境

   cp .env.example .env
   # Edit .env to customize credentials (optional)

1. 启动堆栈

   docker-compose up -d

1. 验证服务

   docker-compose ps
   # Both containers should show "Up" status

1. 访问n8n并创建所有者账户

- 打开浏览器，访问 http://localhost:5678 - 首次运行时，请使用以下信息创建一个所有者账户： - 电子邮箱：your-email@example.com - 姓/名：您的姓名 - 密码：（选择一个安全的密码） - 使用您创建的凭据登录

📖 使用方法

测试MCP集成

1. 导入工作流

- 在n8n用户界面中，点击左侧边栏的“工作流” - 点击“+”或“添加工作流” - 点击“⋮”（三个点）菜单 → “从文件导入” - 选择 workflows/mcp-integration-demo.json 来自项目目录 - 工作流程将在编辑器中打开

1. 激活工作流

- 点击右上角的“激活”切换按钮（应变为绿色/蓝色） - 工作流现已准备好接收Webhook请求

1. 通过Webhook进行测试

   curl -X POST http://localhost:5678/webhook/mcp-demo \
     -H "Content-Type: application/json" \
     -d '{
       "query": "What is the current context?",
       "user_id": "demo-user"
     }'

1. 预期响应

   {
     "success": true,
     "context": [
       {
         "source": "knowledge_base",
         "content": "This is simulated context from MCP",
         "relevance": 0.95
       }
     ],
     "action_result": {
       "success": true,
       "message": "Action process_context executed successfully"
     },
     "timestamp": "2025-10-23T..."
   }

工作流组件

该演示工作流程展示了：

1. Webhook 触发器 - 接收HTTP POST请求
2. MCP上下文请求 - 从MCP服务器获取上下文
3. 上下文验证 - 检查是否返回了有效的上下文
4. 动作执行 - 通过MCP处理上下文
5. 响应格式化 - 返回结构化的JSON响应

🔧 配置

环境变量

定制MCP服务器

MCP服务器是一个嵌入在docker-compose.yml中的简单FastAPI应用程序。要进行自定义：

1. 编辑Python代码中的 docker-compose.yml 在……之下 mcp-server 服务
2. 重启容器： docker-compose restart mcp-server

支持的端点：

• GET /health - 健康检查
• POST /api/context - 获取查询的上下文
• POST /api/execute - 执行一个带有参数的操作

🛠️ 故障排除

常见问题

容器无法启动

# Check port conflicts
docker-compose down
lsof -i :5678  # Mac
netstat -an | findstr 5678  # Windows

# Remove conflicting containers
docker-compose down -v
docker-compose up -d

n8n 显示“未授权”

• 验证凭据在 .env 文件
• 更改后重启容器 .env:

  docker-compose restart

MCP服务器连接失败

# Check MCP server logs
docker logs mcp-server-demo

# Test MCP server directly
curl http://localhost:8080/health

工作流无法激活

• 确保两个容器都在运行
• 检查n8n日志： docker logs n8n-mcp-demo
• 验证MCP_SERVER_URL是否使用了容器名称（mcp-server)，不是 localhost

平台特定说明

Windows（WSL2）

• 确保已启用 WSL2，并且 Docker Desktop 使用 WSL2 后端
• 在 docker-compose 中，文件路径使用 Unix 风格的斜杠
• 在 PowerShell 或 WSL2 终端中运行命令

macOS（中文可译为“苹果电脑操作系统”或直接保留原名，因其为专有名词）

• 在使用之前，必须确保Docker Desktop正在运行 docker-compose up
• 对于M1/M2 Mac电脑，容器使用ARM64架构（完全支持）

📊 性能与扩展

资源使用情况

• n8n 容器约200MB内存，CPU占用率低于5%（空闲状态）
• MCP服务器约100MB内存，CPU占用率\<2%（空闲状态）
• 总磁盘~500MB（包括Docker镜像）

扩展建议

用于生产：

1. 用实际的MCP实现替换模拟的MCP服务器
2. 添加反向代理（Nginx/Traefik）以支持HTTPS
3. 为n8n配置外部数据库（PostgreSQL）
4. 实施适当的密钥管理（使用HashiCorp Vault或AWS Secrets Manager）
5. 添加监控（Prometheus + Grafana）

📁 项目结构

n8n-mcp-demo/
├── .github/
│   └── workflows/         # CI/CD pipelines (optional)
├── config/                # n8n configuration files
├── docs/
│   ├── ARCHITECTURE.md    # Detailed architecture documentation
│   ├── PRESENTATION.md    # Technical presentation slides
│   └── TROUBLESHOOTING.md # Extended troubleshooting guide
├── workflows/
│   └── mcp-integration-demo.json  # Pre-configured workflow
├── .env.example          # Environment template
├── .gitignore            # Git ignore rules
├── docker-compose.yml    # Docker orchestration config
├── LICENSE               # MIT License
└── README.md            # This file

🔒 安全考量

• ⚠️ 更改默认凭据 在生产部署之前
• ⚠️（警告或注意的符号，无具体文字含义） 使用HTTPS 正在生产中（非HTTP）
• ⚠️ 轮换API密钥 定期地
• ⚠️ 网络隔离 - MCP服务器未暴露于公共互联网
• ⚠️ 卷权限 - 确保Docker卷中的文件所有权正确

🤝 贡献（或：参与贡献）

欢迎投稿！请：

1. 克隆仓库
2. 创建一个特性分支（git checkout -b feature/amazing-feature)
3. 提交更改（git commit -m 'Add amazing feature')
4. 推送至分支（git push origin feature/amazing-feature)
5. 打开一个拉取请求

📄 许可证

此项目采用MIT许可证授权——详见 许可证 文件中有详细信息。

🙏 致谢

• n8n - 工作流自动化平台
• FastAPI（快速API） - MCP服务器框架
• - 容器化平台

📞 支持

• 文档见 /docs 文件夹
• 问题：
• 讨论:

______________________________________________________________________

构建于 ❤️（爱心） 针对平台工程师