AI导哈

工作流自动化服务

n8n MCP Server 是一个提供与 n8n 工作流自动化平台交互工具的服务，支持工作流管理、执行、分析和凭证管理等功能，适用于自动化任务处理和开发环境。

  • by visccyber
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 visccyberacct/n8n-mcp-server

使用说明

n8n MCP服务器

MCP服务器提供与n8n.homelab.com上的n8n工作流自动化平台交互的工具。

特性

  • 30 n8n API工具 实现完整的工作流自动化
  • 完整的工作流程CRUD操作（创建、读取、更新、删除）
  • 工作流健康监控和克隆
  • 凭证和标签管理
  • 客户端工作流过滤（名称、活动状态、标签）
  • 提交前工作流验证
  • 异步/等待支持所有操作
  • 安全的API密钥身份验证
  • 家庭实验室环境的SSL/TLS支持
  • 完整的类型提示和文档
  • 生产就绪错误处理
  • 139个具有全面代码覆盖率的测试

工具

工作流管理

  • list_workflows -列出具有可选筛选（名称、活动、标签）的工作流
  • get_workflow -按ID获取特定工作流
  • create_workflow -以编程方式创建新工作流
  • update_workflow -更新现有工作流配置
  • delete_workflow -按ID删除工作流
  • activate_workflow -激活或停用工作流
  • deactivate_workflow -停用工作流
  • get_workflow_version -获取工作流的特定版本
  • transfer_workflow -将工作流转移到其他项目
  • get_workflow_tags -获取分配给工作流的标签
  • update_workflow_tags -更新分配给工作流的标签
  • clone_workflow -克隆具有自动字段清理功能的工作流
  • validate_workflow -创建前验证工作流结构

工作流执行

  • execute_workflow -触发工作流执行
  • get_executions -列出工作流执行历史记录
  • get_execution -按ID获取具体执行细节
  • delete_execution -删除执行历史记录条目
  • retry_execution -重试失败的执行

工作流程分析

  • get_workflow_health -根据最近的执行情况分析工作流运行状况

凭据管理

  • list_credentials -列出所有凭据（仅限ID，数据已编辑）
  • create_credential -创建新凭据
  • update_credential -更新现有凭据
  • delete_credential -删除凭据
  • get_credential_schema -获取凭据类型的架构
  • transfer_credential -将凭据转移到其他项目

标签管理

  • list_tags -列出所有标签
  • create_tag -创建新标签
  • get_tag -按ID获取特定标签
  • update_tag -更新现有标记
  • delete_tag -删除标签

安装

先决条件

  • Python 3.12或更高版本
  • 具有API访问权限的n8n实例（n8n.homeab.com）
  • 已安装Claude CLI(curl -sSL https://claude.ai/install | bash)

设置

cd ~/projects/n8n-mcp-server

# Create virtual environment and install
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
uv pip install -e ".[dev]"

配置

# Copy example environment file
cp .env.example .env

# Edit .env with your n8n API key
# N8N_API_KEY=your_actual_api_key_here

使用Claude代码

注册MCP服务器

claude mcp add n8n-api \
  --env N8N_BASE_URL=https://n8n.homelab.com \
  --env N8N_API_KEY=your_key_here \
  --scope user -- \
  python -m n8n_mcp.server

示例用法

注册后，询问Claude Code：

工作流管理：

  • “列出我的所有n8n工作流”
  • “使用“开始”节点创建简单的工作流”
  • “更新工作流abc123以更改其名称”
  • “删除工作流xyz789”
  • “激活工作流abc123”

工作流执行：

  • “执行工作流ID abc123”
  • “显示最近10次工作流执行”
  • “获取执行exec-456的详细信息”

示例：创建工作流

{
  "name": "My New Workflow",
  "nodes": [
    {
      "id": "start-node",
      "name": "Start",
      "type": "n8n-nodes-base.start",
      "typeVersion": 1,
      "position": [250, 300],
      "parameters": {}
    }
  ],
  "connections": {},
  "settings": {}
}

发展

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=n8n_mcp --cov-report=term-missing

# Run specific test file
pytest tests/test_server.py -v

代码质量

# Format code
ruff format src tests

# Lint code
ruff check src tests

# Type check
mypy src

API兼容性

兼容n8n REST API v1。针对n8n 1.x版本进行了测试。

支持以下n8n API终结点：

  • GET /api/v1/workflows -列出所有工作流
  • GET /api/v1/workflows/{id} -获取工作流详细信息
  • POST /api/v1/workflows -创建新工作流
  • PUT /api/v1/workflows/{id} -更新工作流程
  • DELETE /api/v1/workflows/{id} -删除工作流
  • PATCH /api/v1/workflows/{id} -更新工作流（激活/停用）
  • POST /api/v1/workflows/{id}/execute -执行工作流
  • GET /api/v1/executions -列出执行情况
  • GET /api/v1/executions/{id} -获取执行详细信息

故障排除

身份验证错误

问题：出现“未授权”或“401未经授权”错误

解决方案:

  • 验证N8N_API_KEY是否正确
  • 确保您使用的是USER令牌（而不是项目令牌）
  • 检查API密钥在n8n中是否具有正确的权限

连接错误

问题：无法连接到n8n实例

解决方案:

  • 验证N8N_BASE_URL是否正确(https://n8n.homelab.com)
  • 检查n8n实例的网络访问权限
  • 验证n8n实例是否正在运行
  • 检查防火墙规则（如适用）
  • 对于家庭实验室环境中的SSL证书错误，客户端会自动禁用SSL验证（verify_SSL=False）

未找到工具

问题：Claude Code表示n8n工具不可用

解决方案:

  • 确保MCP服务器已正确注册： claude mcp list
  • 验证注册命令中是否设置了环境变量
  • 注册后重新启动Claude Code
  • 检查MCP服务器日志是否有错误

导入错误

问题：运行服务器时出现模块导入错误

解决方案:

  • 确保虚拟环境已激活
  • 跑 poetry install 或 uv pip install -e .
  • 验证Python版本是否为3.11+

示例工作流

Ubuntu/Debian服务器更新

通过SSH在Ubuntu和Debian服务器上自动更新系统的预构建工作流程。

工作流ID: Ikau3rRnpRG1okvq

看 N8N_服务器_更新_工作流.md 用于：

  • 完整的配置指南
  • SSH设置说明
  • 安全最佳实践
  • 调度选项
  • 故障排除提示

快速开始:

  1. 在n8n中打开工作流：https://n8n.homelab.com/workflow/Ikau3rRnpRG1okvq
  2. 配置SSH凭据
  3. 在“设置服务器列表”节点中更新服务器列表
  4. 手动触发测试
  5. 激活以供生产使用

项目结构

n8n-mcp-server/
├── src/n8n_mcp/
│   ├── __init__.py       # Package initialization
│   ├── server.py         # FastMCP server with 30 tools
│   ├── client.py         # n8n API client wrapper (SSL support)
│   ├── validator.py      # Workflow validation utilities
│   ├── models.py         # Pydantic models for n8n data
│   └── utils.py          # Shared utilities
├── tests/
│   ├── __init__.py
│   └── test_server.py    # 139 tests with comprehensive coverage
├── docs/
│   ├── N8N_API_WORKFLOW_CREATION_REPORT.md  # Detailed API research
│   ├── N8N_SERVER_UPDATE_WORKFLOW.md        # Server update workflow guide
│   ├── CREDENTIAL_TYPES.md                  # Credential type reference
│   ├── CONNECTION_TYPES.md                  # Connection type reference
│   └── KNOWN_LIMITATIONS.md                 # API limitations and workarounds
├── pyproject.toml        # Project dependencies
├── README.md             # This file
└── .env.example          # Example configuration

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请确保：

  • 所有测试均通过(pytest)
  • 代码已格式化(ruff format src tests)
  • 代码已过梁(ruff check src tests)
  • 提供类型提示(mypy src)
  • 文档已更新

支持

对于问题、疑问或贡献，请联系维护人员或在项目存储库中打开问题。

相关 MCP