n8n-mcp-server API 接口详解与使用指南

项目概述

n8n-mcp-server 是一个基于 n8n 工作流自动化平台的 API 服务项目，提供了丰富的 RESTful API 接口，用于管理和操作 n8n 实例中的各种资源。通过这套 API，开发者可以以编程方式管理用户、工作流、凭证、执行记录等核心组件，实现自动化管理和集成。

API 基础信息

该 API 遵循 OpenAPI 3.0 规范，基础路径为 /api/v1，采用 API 密钥认证方式。当前版本为 1.1.1，使用 Sustainable Use License 许可协议。

核心功能模块

1. 系统检查

系统检查功能允许管理员生成系统运行状态报告，检查潜在的问题：

/audit:
  post:
    summary: 生成系统状态报告
    description: 可配置检查范围和标准，如设置工作流闲置天数阈值
    parameters:
      - daysAbandonedWorkflow: 定义多少天未执行视为闲置工作流
      - categories: 指定检查类别(凭证、数据库、节点等)

2. 凭证管理

凭证是 n8n 中连接外部服务的关键配置：

/credentials:
  post:
    summary: 创建新凭证
    description: 为特定节点类型创建认证凭证
    
/credentials/{id}:
  delete:
    summary: 删除凭证
    description: 按ID删除凭证，需为凭证所有者
    
/credentials/schema/{credentialTypeName}:
  get:
    summary: 获取凭证类型Schema
    description: 查询特定凭证类型的数据结构
    examples:
      - freshdeskApi: 需要apiKey和domain
      - slackOAuth2Api: 需要clientId和clientSecret

3. 工作流管理

工作流是 n8n 的核心自动化单元：

/workflows:
  post:
    summary: 创建工作流
  get:
    summary: 获取工作流列表
    parameters:
      - active: 按激活状态过滤
      - tags: 按标签过滤(逗号分隔)
      - name: 按名称过滤
      
/workflows/{id}:
  get:
    summary: 获取单个工作流详情
  put:
    summary: 更新工作流
  delete:
    summary: 删除工作流
    
/workflows/{id}/activate:
  post:
    summary: 激活工作流
    
/workflows/{id}/deactivate:
  post:
    summary: 停用工作流
    
/workflows/{id}/transfer:
  put:
    summary: 转移工作流所有权

4. 执行记录管理

执行记录反映了工作流的运行历史和结果：

/executions:
  get:
    summary: 获取执行记录列表
    parameters:
      - status: 按状态过滤(error/success/waiting)
      - workflowId: 按工作流ID过滤
      
/executions/{id}:
  get:
    summary: 获取单个执行记录详情
  delete:
    summary: 删除执行记录

5. 标签管理

标签用于分类和组织资源：

/tags:
  post:
    summary: 创建新标签
  get:
    summary: 获取标签列表
    
/tags/{id}:
  get:
    summary: 获取标签详情
  put:
    summary: 更新标签
  delete:
    summary: 删除标签

高级功能

分页与过滤

多个列表接口支持分页和过滤：

parameters:
  - limit: 每页记录数
  - cursor: 分页游标
  - active: 布尔过滤条件
  - tags: 多标签过滤

项目隔离

部分接口支持 projectId 参数，实现多项目环境下的资源隔离：

parameters:
  - projectId: 项目标识符

最佳实践建议

1. 凭证安全：通过 API 创建凭证时，确保传输层加密，并定期轮换凭证

2. 工作流版本控制：更新工作流前，建议先获取当前版本作为备份

3. 执行记录清理：定期清理旧的执行记录以优化存储

4. 系统检查自动化：设置定期检查任务，监控系统运行状态

5. 标签策略：建立统一的标签命名规范，便于资源管理

错误处理

API 遵循标准 HTTP 状态码：

• 401 Unauthorized: 认证失败
• 404 Not Found: 资源不存在
• 400 Bad Request: 请求参数错误
• 409 Conflict: 资源冲突
• 500 Internal Server Error: 服务器内部错误

总结

n8n-mcp-server 的 API 设计遵循 RESTful 原则，提供了完整的工作流自动化管理能力。通过合理利用这些接口，开发者可以构建强大的自动化运维工具，实现 n8n 实例的规模化管理和监控。建议结合具体业务场景，设计适当的调用策略和错误处理机制，确保系统的稳定性和安全性。