n8n工作流管理服务器

n8n MCP服务器

一个全面的模型上下文协议（MCP）服务器，为AI助手提供对n8n工作流、执行、凭据等的完全编程访问。

🚀 特性

完成n8n API覆盖范围

• 工作流管理：创建、读取、更新、删除、激活、停用工作流
• 执行管理：列表、获取、删除、触发、重试、停止执行
• 凭据管理：创建、读取、更新、删除、测试凭据
• 标签管理：创建、列出、删除标签
• 用户管理：列出并获取用户信息
• 变量管理：创建、读取、更新、删除变量
• 文件上传：将文件上传到n8n（如果支持）
• 健康监测：检查API连接和运行状况

高级功能

• 全面的错误处理：详细的错误代码和消息
• 记录系统：基于Winston的日志记录，具有多个级别和类别
• 输入验证：对所有输入进行基于Zod的模式验证
• 重试逻辑：暂时性故障的自动重试
• 速率限制：内置速率限制处理
• 类型安全：具有严格类型的完全TypeScript支持

📋 先决条件

• Node.js 18.0.0或更高版本
• 具有API访问权限的n8n实例
• n8n API密钥

🛠️ 安装

1. 克隆存储库

   复制

   git clone https://github.com/your-org/n8n-mcp-server.git
   cd n8n-mcp-server
   

2. 安装依赖项

   复制

   npm install
   

3. 配置环境变量

   复制

   cp .env.example .env
   

   编辑 .env 使用n8n配置：

   复制

   N8N_API_URL=http://localhost:5678/api/v1
   N8N_API_KEY=your-api-key-here
   LOG_LEVEL=info
   NODE_ENV=development
   

4. 构建项目

   复制

   npm run build
   

🚀 用法

启动服务器

npm start

发展模式

npm run dev

测试

npm test
npm run test:coverage

🔌 MCP客户端配置

要将此MCP服务器与Claude Desktop或其他MCP客户端一起使用，请添加以下配置：

Claude桌面配置

添加到您的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": {
      "command": "node",
      "args": ["/path/to/n8n-mcp-server/start.js"],
      "env": {
        "N8N_API_URL": "http://localhost:5678/api/v1",
        "N8N_API_KEY": "your-n8n-api-key",
        "LOG_LEVEL": "info"
      }
    }
  }
}

配置选项

MCP服务器在客户端配置中接受以下环境变量：

获取n8n API密钥

1. 登录您的n8n实例
2. 首选 设置 → API
3. 生成新的API密钥
4. 复制密钥并将其添加到MCP客户端配置中

验证连接

配置后，MCP客户端应能够：

1. 列出n8n服务器上的可用工具
2. 执行工作流操作
3. 管理凭据和执行

您可以通过让AI助手列出可用的n8n工作流或检查API连接状态来验证连接。

📚 可用工具

工作流工具

执行工具

凭证工具

管理工具

实用工具

🔧 配置

环境变量

日志记录级别

• error：只有错误消息
• warn：警告和错误消息
• info：信息、警告和错误消息
• debug：调试、信息、警告和错误消息
• verbose：所有消息

🏗️ 项目结构

n8n-mcp-server/
├── src/
│   ├── api/
│   │   └── n8n-client.ts          # n8n API client
│   ├── config/
│   │   ├── environment.ts         # Environment configuration
│   │   └── server.ts              # Server configuration
│   ├── errors/
│   │   ├── error-codes.ts         # Error code definitions
│   │   └── index.ts               # Error handling utilities
│   ├── tools/
│   │   ├── base-handler.ts        # Base tool handler classes
│   │   ├── workflow/              # Workflow tool handlers
│   │   ├── execution/             # Execution tool handlers
│   │   ├── credentials/           # Credential tool handlers
│   │   └── upload/                # Upload tool handlers
│   ├── types/
│   │   └── index.ts               # Type definitions
│   ├── utils/
│   │   └── logger.ts              # Logging utilities
│   └── index.ts                   # Main entry point
├── tests/
│   ├── unit/                      # Unit tests
│   ├── integration/               # Integration tests
│   ├── fixtures/                  # Test fixtures
│   └── mocks/                     # Test mocks
├── build/                         # Compiled JavaScript
├── logs/                          # Log files
├── templates/                     # Workflow templates
├── package.json
├── tsconfig.json
├── jest.config.js
└── README.md

🧪 测试

运行测试

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Run specific test file
npm test -- --testNamePattern="list_workflows"

测试结构

• 单元测试：测试单个函数和类
• 集成测试：测试API交互和工具处理程序
• 夹具：测试数据和模拟响应
• 模拟考试：外部依赖关系的模拟实现

📝 api参考

n8n涵盖的API终点

工作流

• GET /workflows -列出工作流
• GET /workflows/{id} -获取工作流
• POST /workflows -创建工作流
• PUT /workflows/{id} -更新工作流程
• DELETE /workflows/{id} -删除工作流
• POST /workflows/{id}/activate -激活工作流
• POST /workflows/{id}/deactivate -停用工作流
• POST /workflows/{id}/tags -更新工作流标签
• POST /workflows/{id}/transfer -转移工作流所有权

执行

• GET /executions -列出执行情况
• GET /executions/{id} -执行
• DELETE /executions/{id} -删除执行
• POST /executions -触发器执行
• POST /executions/{id}/retry -重试执行
• POST /executions/{id}/stop -停止执行

凭证

• GET /credentials -列出凭据
• GET /credentials/{id} -获取凭证
• POST /credentials -创建凭据
• PUT /credentials/{id} -更新凭据
• DELETE /credentials/{id} -删除凭据
• POST /credentials/{id}/test -测试证书
• POST /credentials/{id}/transfer -转移凭证所有权

标签

• GET /tags -列表标签
• GET /tags/{id} -获取标签
• POST /tags -创建标签
• PUT /tags/{id} -更新标签
• DELETE /tags/{id} -删除标签

用户

• GET /users -列出用户
• GET /users/{id} -获取用户

变量

• GET /variables -列出变量
• GET /variables/{id} -获取变量
• POST /variables -创建变量
• PUT /variables/{id} -更新变量
• DELETE /variables/{id} -删除变量

🔒 安全

• API密钥安全地存储在环境变量中
• 所有API请求都经过身份验证
• 输入验证可防止注入攻击
• 错误消息不会暴露敏感信息
• 日志记录不包括敏感数据

🚀 部署

Docker部署

FROM node:18-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .
RUN npm run build

EXPOSE 3000

CMD ["npm", "start"]

环境特定配置

发展

NODE_ENV=development
LOG_LEVEL=debug

生产

NODE_ENV=production
LOG_LEVEL=info

测试

NODE_ENV=test
LOG_LEVEL=error

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

开发指南

• 遵循TypeScript的最佳实践
• 编写全面的测试
• 为所有公共API添加JSDoc注释
• 遵循现有代码样式
• 更新新功能的文档

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🆘 支持

• 文档: 维基工程
• 问题: GitHub问题
• 讨论: GitHub讨论

🙏 致谢

• n8n -工作流自动化平台
• 模型上下文协议 -MCP规范
• 温斯顿 -日志库
• 萨德 -TypeScript第一模式验证

📊 状态