n8n-mcp API参考：深入了解MCP服务器的所有可用接口
n8n-mcp API参考：深入了解MCP服务器的所有可用接口
【免费下载链接】n8n-mcp 
项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp
n8n-mcp（Model Context Protocol）服务器提供了一系列强大的API接口，帮助开发者构建、验证和优化n8n工作流。本文档详细介绍所有可用接口，包括节点管理、工作流验证、模板查询等核心功能，适用于希望充分利用MCP服务器能力的开发者和运营人员。
API架构概览
MCP服务器采用模块化架构，主要包含初始化、工具调用和协议协商三大核心功能。服务器实现位于src/mcp/server.ts，通过TypeScript接口确保类型安全。
核心API模块划分如下：
- 节点管理：搜索、查询和验证n8n节点
- 工作流验证：检查节点配置、连接和表达式合法性
- 模板系统：查询和检索工作流模板
- AI工具集成：将任意节点转换为AI可用工具
Mermaid流程图展示API调用流程：
核心API接口详解
初始化接口
初始化接口是建立MCP连接的第一个调用，用于协商协议版本和交换服务器/客户端能力。
请求参数：
{
"protocolVersion": "1.0.0",
"capabilities": {
"tools": {}
},
"clientInfo": {
"name": "n8n-desktop",
"version": "1.8.0"
}
}
响应示例：
{
"protocolVersion": "1.0.0",
"capabilities": {
"tools": {}
},
"serverInfo": {
"name": "n8n-documentation-mcp",
"version": "2.18.3"
}
}
实现细节见N8NDocumentationMCPServer类的构造函数和初始化逻辑，服务器会自动检查数据库健康状态并加载节点元数据。
节点管理接口
节点管理接口提供全面的n8n节点查询和信息检索功能，支持按类别、包名和AI能力过滤。
list_nodes
列出n8n节点，支持多条件过滤。常用场景：浏览触发器节点或特定类别节点。
请求示例：
{
"category": "trigger",
"limit": 50
}
响应示例：
{
"nodes": [
{
"node_type": "nodes-base.webhook",
"display_name": "Webhook",
"description": "Trigger workflows with incoming HTTP requests",
"category": "trigger",
"is_trigger": 1,
"is_webhook": 1
},
// 更多节点...
],
"total": 12,
"limit": 50,
"offset": 0
}
接口定义见tools.ts，支持的过滤参数包括package、category、developmentStyle和isAITool。
get_node_essentials
获取节点基本信息，包括核心属性和使用示例，比get_node_info更轻量。
请求示例：
{
"nodeType": "nodes-base.httpRequest",
"includeExamples": true
}
响应示例：
{
"nodeType": "nodes-base.httpRequest",
"displayName": "HTTP Request",
"description": "Make HTTP requests to any API endpoint",
"essentialProperties": [
{
"name": "method",
"type": "string",
"required": true,
"enum": ["GET", "POST", "PUT", "DELETE"]
},
{
"name": "url",
"type": "string",
"required": true,
"description": "API endpoint URL"
}
],
"examples": [
{
"name": "GET request to JSONPlaceholder",
"config": {
"method": "GET",
"url": "https://jsonplaceholder.typicode.com/todos/1"
}
}
]
}
接口实现会从NodeRepository获取节点数据，并应用PropertyFilter提取核心属性。
工作流验证接口
验证接口是MCP服务器的核心能力，提供从节点配置到完整工作流的多层次验证。
validate_node_operation
验证节点配置的合法性，支持四种验证配置文件，满足不同场景需求。
请求示例：
{
"nodeType": "nodes-base.slack",
"config": {
"resource": "channel",
"operation": "create",
"channelName": "new-channel"
},
"profile": "ai-friendly"
}
响应示例：
{
"nodeType": "nodes-base.slack",
"displayName": "Slack",
"valid": true,
"errors": [],
"warnings": [
{
"type": "suggestion",
"property": "channelName",
"message": "Channel name should be lowercase with hyphens",
"suggestion": "new-channel-name"
}
],
"suggestions": [
"Consider adding a 'topic' to describe the channel purpose"
],
"summary": {
"hasErrors": false,
"errorCount": 0,
"warningCount": 1,
"suggestionCount": 1
}
}
验证逻辑由EnhancedConfigValidator实现，结合节点相似度服务提供智能建议。
validate_workflow
完整工作流验证，检查节点配置、连接和表达式，是部署前的必备步骤。
请求示例：
{
"workflow": {
"nodes": [
{
"id": "n1",
"type": "nodes-base.webhook",
"parameters": {}
},
{
"id": "n2",
"type": "nodes-base.httpRequest",
"parameters": {
"method": "GET",
"url": "{{$node["n1"].parameter.url}}"
}
}
],
"connections": {
"n1": {
"main": [
[
{
"node": "n2",
"type": "main",
"index": 0
}
]
]
}
}
},
"options": {
"validateNodes": true,
"validateConnections": true,
"validateExpressions": true
}
}
响应示例：
{
"valid": false,
"summary": {
"totalNodes": 2,
"enabledNodes": 2,
"triggerNodes": 1,
"validConnections": 1,
"invalidConnections": 0,
"expressionsValidated": 1,
"errorCount": 1,
"warningCount": 0
},
"errors": [
{
"node": "n1",
"message": "Webhook node is missing path parameter",
"details": "Webhook requires a path for the HTTP endpoint"
}
],
"warnings": [],
"suggestions": [
"Add a path like '/webhook-endpoint' to the Webhook node"
]
}
工作流验证服务WorkflowValidator会依次检查节点配置、连接合法性和表达式语法。
模板接口
模板接口提供工作流模板的发现、查询和检索功能，帮助用户快速构建新工作流。
list_templates
列出所有模板，支持分页和排序，可选择包含AI生成的元数据以实现智能过滤。
请求示例：
{
"limit": 10,
"offset": 0,
"sortBy": "views",
"includeMetadata": true
}
响应示例：
{
"templates": [
{
"id": 1,
"name": "Slack Notification on Form Submission",
"description": "Send Slack messages when a Google Form is submitted",
"nodeCount": 3,
"views": 1254,
"metadata": {
"category": "communication",
"complexity": "simple",
"setupTimeMinutes": 15,
"requiredServices": ["google", "slack"]
}
},
// 更多模板...
],
"total": 42,
"limit": 10,
"offset": 0
}
模板数据存储在SQLite数据库中，通过TemplateService提供访问接口。
get_templates_for_task
按任务类型获取精选模板，支持常见自动化场景如数据同步、Webhook处理和AI自动化。
请求示例：
{
"task": "slack_integration",
"limit": 5
}
响应示例：
{
"templates": [
{
"id": 1,
"name": "Slack Notification on Form Submission",
"description": "Send Slack messages when a Google Form is submitted",
"nodeCount": 3,
"views": 1254
},
{
"id": 5,
"name": "Slack Command to Run Workflow",
"description": "Trigger workflows using Slack slash commands",
"nodeCount": 4,
"views": 892
}
],
"total": 8,
"limit": 5,
"offset": 0
}
任务分类定义在tools.ts，包括ai_automation、data_sync、webhook_processing等11种任务类型。
高级功能接口
AI工具集成
MCP服务器提供将任意n8n节点转换为AI工具的能力，通过get_node_as_tool_info接口获取详细的工具使用指南。
请求示例：
{
"nodeType": "nodes-base.googleSheets"
}
响应示例：
{
"nodeType": "nodes-base.googleSheets",
"displayName": "Google Sheets",
"toolCapabilities": "Read/write data to Google Sheets spreadsheets",
"aiToolRequirements": {
"credentials": true,
"setupSteps": 3,
"examplePrompt": "Add a row to Google Sheet with data: {{ $json }}"
},
"toolParameters": {
"spreadsheetId": "Required. The ID of the Google Sheet",
"range": "Required. Sheet name and cell range (e.g., 'Sheet1!A1:B10')",
"operation": "Required. One of: read, write, append, update"
},
"examples": [
{
"task": "Append data to spreadsheet",
"parameters": {
"operation": "append",
"spreadsheetId": "1abc123...",
"range": "Data!A1",
"values": "{{ $json }}"
}
}
]
}
接口实现位于get_node_as_tool_info，会分析节点属性并生成AI友好的工具描述。
搜索接口
MCP服务器提供强大的搜索能力，支持节点和模板的全文检索，使用SQLite FTS5引擎实现高性能搜索。
search_nodes
搜索节点，支持关键词、模糊匹配和精确短语搜索，返回相关节点及匹配分数。
请求示例：
{
"query": "http request",
"mode": "AND",
"limit": 5,
"includeExamples": true
}
响应示例：
{
"nodes": [
{
"node_type": "nodes-base.httpRequest",
"display_name": "HTTP Request",
"description": "Make HTTP requests to any API endpoint",
"category": "core",
"matchScore": 0.98,
"examples": [
{
"name": "GET request to JSONPlaceholder",
"config": {
"method": "GET",
"url": "https://jsonplaceholder.typicode.com/todos/1"
}
}
]
},
// 更多节点...
],
"total": 3,
"limit": 5,
"offset": 0
}
搜索实现位于NodeRepository的searchNodes方法，使用FTS5索引加速搜索。
API调用最佳实践
节点发现与配置流程
推荐的节点使用流程：搜索→获取基本信息→验证配置，可最大限度减少API调用次数并提高配置准确性。
- 使用search_nodes查找相关节点
- 调用get_node_essentials获取核心属性
- 使用validate_node_operation验证配置
- 必要时调用get_property_dependencies了解属性依赖关系
代码示例：
// 搜索HTTP相关节点
const httpNodes = await mcpClient.callTool('search_nodes', { query: 'http', limit: 5 });
// 获取HTTP Request节点基本信息
const httpInfo = await mcpClient.callTool('get_node_essentials', {
nodeType: 'nodes-base.httpRequest',
includeExamples: true
});
// 验证HTTP Request配置
const validation = await mcpClient.callTool('validate_node_operation', {
nodeType: 'nodes-base.httpRequest',
config: {
method: 'GET',
url: 'https://api.example.com/data'
}
});
if (validation.valid) {
// 配置有效，继续构建工作流
} else {
// 处理错误
console.error('Validation errors:', validation.errors);
}
工作流开发流程
完整工作流开发应遵循"设计→验证→优化"三阶段流程，确保工作流的正确性和性能。
- 使用list_templates或get_templates_for_task查找起点模板
- 调用validate_workflow验证完整工作流
- 根据验证结果优化节点配置和连接
- 使用validate_workflow_expressions检查表达式
错误处理与调试
MCP API提供详细的错误信息，帮助开发者快速定位和解决问题。错误响应包含错误类型、详细描述和可能的修复建议。
常见错误类型：
- MissingRequiredField：节点缺少必填属性
- InvalidConnection：工作流连接指向不存在的节点
- ExpressionSyntaxError：n8n表达式语法错误
- NodeTypeNotFound：请求的节点类型不存在
错误响应示例：
{
"content": [
{
"type": "text",
"text": "Error executing tool validate_node_operation: Missing required field 'method'"
}
],
"isError": true,
"errorDetails": {
"type": "MissingRequiredField",
"field": "method",
"suggestion": "Add method field with one of: GET, POST, PUT, DELETE"
}
}
调试技巧：
- 使用validate_node_minimal快速检查必填字段
- 调用get_property_dependencies了解属性间依赖关系
- 使用mode=FULL参数获取更详细的错误上下文
总结与资源
MCP服务器API提供了构建、验证和优化n8n工作流所需的全部工具，主要优势包括：
- 全面的节点知识：525+节点的详细信息和使用示例
- 强大的验证能力：从节点到工作流的多层次验证
- 丰富的模板库：40+精选模板覆盖常见自动化场景
- AI友好设计：专为AI代理设计的接口和响应格式
官方资源：
- MCP服务器源码：src/mcp/
- 节点数据库结构：src/database/schema.sql
- 测试用例：tests/integration/mcp/
- API示例：examples/enhanced-documentation-demo.js
通过这些API接口，开发者和AI代理可以高效构建可靠的n8n工作流，减少配置错误并加速开发过程。无论您是构建简单的自动化任务还是复杂的集成流程，MCP服务器API都能提供必要的支持和指导。
【免费下载链接】n8n-mcp 项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp
