n8n-mcp 节点发现工具完全指南：search_nodes 与 get

n8n-mcp 节点发现工具完全指南：search_nodes 与 get_node 的深度用法

【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp

导读

本文是 n8n-mcp 项目中 n8n-mcp-tools-expert 技能包的节点发现（Node Discovery）专项指南，围绕search_nodes与get_node两个 MCP 工具展开。你将学会：如何用关键词在 800+ 节点中秒级定位目标节点、如何按三种详情级别与七种模式精确获取节点配置信息、如何区分nodes-base.*与n8n-nodes-base.*两种 nodeType 前缀格式，以及如何在真实工作流中组合这些工具完成「搜索 → 配置 → 校验」的完整链路。读完本文，你可以在 Claude Desktop、Claude Code、Windsurf、Cursor 等 MCP 客户端中像专家一样高效地发现并配置任何 n8n 节点。

一、节点发现工具全景：search_nodes 与 get_node 的分工

在 n8n-mcp 的 40+ 个 MCP 工具中，节点发现（Node Discovery）由两个工具承担，分工明确：

工具	核心职责	典型延迟	输出体量
`search_nodes`	按关键词在全部节点中定位目标	<20ms（复杂 FUZZY 查询 <50ms）	小
`get_node`	获取单个节点的配置详情与版本信息	minimal/standard <10ms，full <100ms	200 ～ 8K tokens

search_nodes解决「找哪个节点」，get_node解决「这个节点怎么配」。二者配合validate_node（见 VALIDATION_GUIDE.md）即可完成从发现到落地的完整闭环，这也是本技能包推荐的最高频使用范式：

search_nodes → get_node(standard) → validate_node

二、search_nodes：秒级全文检索

search_nodes是技能包标注的START HERE!入口工具，在工具定义中将其定位为按关键词搜索 n8n 节点的全文检索工具。

2.1 参数说明

search_nodes({ query: "slack", // 必填：搜索关键词 mode: "OR", // 可选：OR（默认）、AND、FUZZY limit: 20, // 可选：最大返回条数（默认 20，上限 100） source: "all", // 可选：all、core、community、verified includeExamples: false // 可选：是否附带模板真实配置示例 })

各参数详解（依据工具文档与参数校验）：

query（必填）：搜索关键词。支持用双引号包裹精确短语，如"google sheets"；若传入完整的 nodeType（如n8n-nodes-base.slack），服务端会自动将其归一化为短前缀格式再检索。
mode（可选，默认OR）：OR匹配任意一个词；AND要求所有词同时出现；FUZZY为容错模式，能处理拼写错误（slak→ Slack）。
limit（可选，默认 20）：最大返回结果数，上限 100。
source（可选，默认all）：来源过滤。core仅内置节点，community仅社区节点，verified仅已验证社区节点。
includeExamples（可选，默认false）：为每个节点附带来自热门模板的前 2 个真实配置示例，每个节点约增加 200-400 tokens。
includeOperations（可选，默认false）：直接附带每个节点的 resource/operation 树（每个结果约 100-300 tokens），省去一次get_node往返；仅对具有 resource/operation 模式的节点返回，触发器节点与自由表单节点（Code、HTTP Request）会省略该字段。

2.2 返回结构

{ "query": "slack", "results": [ { "nodeType": "nodes-base.slack", // 供 search/validate 工具使用 "workflowNodeType": "n8n-nodes-base.slack", // 供工作流工具使用 "displayName": "Slack", "description": "Consume Slack API", "category": "output", "relevance": "high", "operationsTree": { /* includeOperations: true 时返回 */ }, // 社区节点额外返回： // isCommunity: true, isVerified: boolean, // authorName: string, npmDownloads: number } ], "totalCount": 20 }

2.3 底层实现：SQLite FTS5 全文索引

search_nodes的毫秒级性能来源于 SQLite FTS5 全文索引。从 server.ts 的实现可以看到完整调用链：

先对查询做归一化：若包含n8n-nodes-base.或@n8n/n8n-nodes-langchain.前缀，自动替换为短前缀；
检测nodes_fts表是否存在；
存在则走searchNodesFTS（FTS5 全文检索 + 排名），否则回退到searchNodesLIKE（LIKE 查询兜底）。

FTS5 路径的核心 SQL（server.ts）将节点表与 FTS5 索引按 rowid 连接，并使用MATCH语法匹配；排序采用「精确显示名匹配 > 相关度评分 > FTS rank」的三级策略，保证高频节点（HTTP Request、Webhook、Set、Code、Slack）优先展示。FTS5 不可用或表缺失时，启动检查会输出警告，提示执行npm run rebuild重建索引，此时性能会降级为 LIKE 扫描。

三种模式对应的 FTS 查询构造（server.ts）：

OR：词之间以OR连接（默认）；
AND：词之间以AND连接；
FUZZY：不走 FTS5，改走独立的模糊匹配实现searchNodesFuzzy（server.ts）。

source过滤在 SQL 层以is_community/is_verified标志位实现：core追加AND n.is_community = 0，community追加AND n.is_community = 1，verified追加AND n.is_community = 1 AND n.is_verified = 1（server.ts）。

2.4 使用建议

从单个关键词起步，结果最广；
用户可能拼错节点名时优先用FUZZY；
2-3 个词的精确检索用AND；
生产环境推荐社区节点时用source: "verified"并检查isVerified标志；
注意：AND模式会搜索名称与描述全部字段；FUZZY对 1-2 个字符的超短查询可能返回意外结果；引号内精确短语区分大小写。

三、get_node：统一节点信息查询

get_node是技能包中信息量最集中的工具，在工具定义中定位为「渐进式详情级别 + 多种模式的统一节点信息工具」。其入口参数在 getNodeInfo 实现中完成校验：detail仅接受minimal/standard/full，mode仅接受info/versions/compare/breaking/migrations（docs与search_properties在分发层单独处理），非法值会直接抛出参数错误。nodeType 在进入处理前会经NodeTypeNormalizer.normalizeToFullForm归一化，保证短前缀也能被正确解析。

3.1 三级详情（mode="info"）

详情级别	Token 开销	适用场景
`minimal`	~200	快速元数据核查
`standard`	~1-2K	大多数场景（默认）
`full`	~3-8K	仅复杂调试

minimal（<5ms）：仅返回 nodeType、displayName、description、category 等基础元数据（server.ts），同时附带isAITool、isTrigger、isWebhook标志；若节点未命中，会遍历getNodeTypeAlternatives尝试别名解析。
standard（<10ms，推荐）：在基础信息之上叠加可用 operations、10-20 个最常用属性、元数据（isAITool / isTrigger / hasCredentials），并附版本摘要versionInfo；启用includeExamples: true时附带模板中的真实配置示例。
full（<100ms，谨慎使用）：返回完整节点 schema，体积约 100KB，仅在 standard 无法满足复杂调试需求时使用。

// standard（默认） get_node({ nodeType: "nodes-base.slack", includeExamples: true }) // minimal get_node({ nodeType: "nodes-base.slack", detail: "minimal" }) // full get_node({ nodeType: "nodes-base.httpRequest", detail: "full" })

3.2 七种模式速查

模式	用途	关键参数
`info`（默认）	按详情级别返回节点 schema	`detail`
`docs`	人类可读的 Markdown 文档（含用法示例、认证指南、常见模式、最佳实践）	—
`search_properties`	查找节点内特定属性	`propertyQuery`（必填）、`maxPropertyResults`（默认 20）
`versions`	版本历史与破坏性变更标记	—
`compare`	对比两个版本的属性级差异	`fromVersion`（必填）、`toVersion`（默认最新）
`breaking`	仅列出破坏性变更	`fromVersion`（必填）
`migrations`	列出可自动迁移的变更	`fromVersion`、`toVersion`（均必填）

版本类模式的参数约束在 handleVersionMode 中强制校验：compare与breaking要求fromVersion，migrations要求同时提供fromVersion与toVersion，缺失即抛错。

// docs：可读文档 get_node({ nodeType: "nodes-base.slack", mode: "docs" }) // search_properties：查找 auth 相关字段 get_node({ nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "auth" }) // versions：版本历史 get_node({ nodeType: "nodes-base.executeWorkflow", mode: "versions" }) // compare：对比 3.0 → 4.1 get_node({ nodeType: "nodes-base.httpRequest", mode: "compare", fromVersion: "3.0", toVersion: "4.1" }) // breaking：仅破坏性变更 get_node({ nodeType: "nodes-base.httpRequest", mode: "breaking", fromVersion: "3.0" }) // migrations：可自动迁移项 get_node({ nodeType: "nodes-base.httpRequest", mode: "migrations", fromVersion: "3.0" })

3.3 两个增强参数

includeTypeInfo：为属性附加类型结构元数据（校验规则、JS 类型），每个属性约增加 80-120 tokens。适用于 filter、resourceMapper 等结构复杂的节点。源码层面通过enrichPropertiesWithTypeInfo对 standard 的 requiredProperties / commonProperties 以及 full 的完整属性列表做类型信息富化（server.ts）。
includeExamples：附带模板中的真实世界配置示例，每个示例约增加 200-400 tokens。注意：仅对mode: "info"+detail: "standard"生效，这是源码中明确限定的组合。

四、nodeType 前缀格式（关键约定）

这是本技能包强调的CRITICAL约定——不同工具族对节点类型的书写格式要求不同：

Search / Validate 工具族（短前缀）：

"nodes-base.slack" "nodes-base.httpRequest" "nodes-langchain.agent"

Workflow 工具族（完整前缀）：

"n8n-nodes-base.slack" "n8n-nodes-base.httpRequest" "@n8n/n8n-nodes-langchain.agent"

好消息是search_nodes的返回结果同时携带两种格式，直接按需取用即可：

{ "nodeType": "nodes-base.slack", // 配合 get_node、validate_node "workflowNodeType": "n8n-nodes-base.slack" // 配合 n8n_create_workflow }

底层归一化由 node-type-normalizer.ts 的normalizeToFullForm完成：它统一识别n8n-nodes-base.webhook、nodes-base.webhook、@n8n/n8n-nodes-langchain.agent等写法并转换为规范形式；search_nodes的查询侧也会在入口处自动完成反方向归一化，因此即使你误传完整前缀，检索也能正常进行。

五、实战流程：从搜索到配置的完整链路

5.1 标准四步流程（技能包推荐）

Step 1: Search search_nodes({query: "slack"}) → Returns: nodes-base.slack Step 2: Get Operations（平均思考时间约 18s） get_node({ nodeType: "nodes-base.slack", includeExamples: true }) → Returns: operations 列表 + 示例配置 Step 3: Validate Config validate_node({ nodeType: "nodes-base.slack", config: {resource: "channel", operation: "create"}, profile: "runtime" }) → Returns: 校验结果 Step 4: Use in Workflow （配置就绪，可写入工作流）

最常用的组合是search → get_node，两次调用平均即可完成节点定位与配置获取。

5.2 案例一：查找并配置 HTTP Request

// 第 1 步：搜索 search_nodes({query: "http request"}) // 第 2 步：获取标准信息 get_node({nodeType: "nodes-base.httpRequest"}) // 第 3 步：查找认证相关选项 get_node({ nodeType: "nodes-base.httpRequest", mode: "search_properties", propertyQuery: "authentication" }) // 第 4 步：校验配置 validate_node({ nodeType: "nodes-base.httpRequest", config: {method: "POST", url: "https://api.example.com"}, profile: "runtime" })

5.3 案例二：探索 AI 节点

// 查找所有 AI 相关节点 search_nodes({query: "ai agent", source: "all"}) // 获取 AI Agent 的可读文档 get_node({nodeType: "nodes-langchain.agent", mode: "docs"}) // 获取带示例的配置详情 get_node({ nodeType: "nodes-langchain.agent", includeExamples: true })

5.4 案例三：升级前检查版本兼容性

// 查看全部版本 get_node({nodeType: "nodes-base.executeWorkflow", mode: "versions"}) // 检查 v1 → v2 的破坏性变更 get_node({ nodeType: "nodes-base.executeWorkflow", mode: "breaking", fromVersion: "1.0" })

在升级 n8n 实例前，先执行breaking/migrations模式评估影响面，可显著降低工作流被破坏的风险；这两类模式与仓库中的破坏性变更注册与自动修复服务（如 breaking-changes-registry.ts、node-migration-service.ts）同属一个能力体系。

六、工具选择速查表

工具 / 模式	何时使用	速度	体量
`search_nodes`	按关键词找节点	<20ms	小
`get_node (standard)`	获取配置（默认）	<10ms	1-2K
`get_node (minimal)`	快速元数据核查	<5ms	200
`get_node (full)`	复杂调试	<100ms	3-8K
`get_node (docs)`	学习节点用法	快	中
`get_node (search_properties)`	查找特定字段	快	小
`get_node (versions)`	检查版本历史	快	小

核心最佳实践：search_nodes→get_node(standard)→validate_node。

另需注意get_node的 Token 成本模型：minimal ~200、standard ~1000-2000（默认）、full ~3000-8000；includeTypeInfo每属性 +80-120，includeExamples每示例 +200-400，版本类模式约 400-1200。合理控制详情级别与增强参数，是保持 MCP 会话上下文高效的关键。

七、配套资源

SEARCH_GUIDE.md：本文的原始指南（节点发现工具）；
VALIDATION_GUIDE.md：validate_node的校验模式与四种 profile（minimal/runtime/ai-friendly/strict）；
WORKFLOW_GUIDE.md：节点在工作流中的使用与 18 种工作流管理操作；
SKILL.md：工具选择总览与 nodeType 格式说明；
工具实现：tools.ts（工具与输入 schema）、server.ts（search_nodes / get_node 核心实现）、search-nodes.ts 与 get-node.ts（工具文档）；
类型归一化：node-type-normalizer.ts；
搜索索引构建：可参考 prebuild-fts5.ts 与 migrate-nodes-fts.ts 了解 FTS5 索引的建立与迁移方式。

【免费下载链接】n8n-mcpA MCP for Claude Desktop / Claude Code / Windsurf / Cursor to build n8n workflows for you项目地址: https://gitcode.com/GitHub_Trending/n8/n8n-mcp

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考