n8n-mcp-tools-expert

n8n MCP 工具專家

使用 n8n-mcp MCP 伺服器工具建立工作流程的完整指南。

---

工具分類

n8n-mcp 提供的工具分類如下：

1. 節點探索 → SEARCH_GUIDE.md
2. 設定驗證 → VALIDATION_GUIDE.md
3. 工作流程管理 → WORKFLOW_GUIDE.md
4. 範本庫 - 搜尋並部署 2,700 多個真實工作流程
5. 資料表 - 管理 n8n 資料表與資料列 (n8n_manage_datatable)
6. 憑證管理 - 完整的憑證 CRUD + 結構探索 (n8n_manage_credentials)
7. 安全與稽核 - 執行個體安全稽核，支援自訂深度掃描 (n8n_audit_instance)
8. 文件與指南 - 工具文件、AI 代理指南、程式碼節點指南

---

快速參考

最常用工具（依成功率排序）

工具	使用時機	速度
search_nodes	依關鍵字搜尋節點	<20ms
get_node	了解節點操作 (detail="standard")	<10ms
validate_node	檢查設定 (mode="full")	<100ms
n8n_create_workflow	建立工作流程	100-500ms
n8n_update_partial_workflow	編輯工作流程（最常用！）	50-200ms
validate_workflow	檢查完整工作流程	100-500ms
n8n_deploy_template	部署範本至 n8n 執行個體	200-500ms
n8n_manage_datatable	管理資料表與資料列	50-500ms
n8n_manage_credentials	憑證 CRUD + 結構探索	50-500ms
n8n_audit_instance	安全稽核（內建 + 自訂掃描）	500-5000ms
n8n_autofix_workflow	自動修復驗證錯誤	200-1500ms

---

工具選擇指南

尋找正確的節點

工作流程：

1. search_nodes({query: "關鍵字"})
2. get_node({nodeType: "nodes-base.名稱"})
3. [選擇性] get_node({nodeType: "nodes-base.名稱", mode: "docs"})

範例：

// 步驟 1：搜尋
search_nodes({query: "slack"})
// 回傳：nodes-base.slack

// 步驟 2：取得詳細資訊
get_node({nodeType: "nodes-base.slack"})
// 回傳：操作、屬性、範例（標準詳細度）

// 步驟 3：取得可讀文件
get_node({nodeType: "nodes-base.slack", mode: "docs"})
// 回傳：markdown 文件

常見模式：search → get_node（平均 18 秒）

驗證設定

工作流程：

1. validate_node({nodeType, config: {}, mode: "minimal"}) - 檢查必填欄位
2. validate_node({nodeType, config, profile: "runtime"}) - 完整驗證
3. [重複] 修正錯誤，再次驗證

常見模式：validate → fix → validate（思考 23 秒，每次修正 58 秒）

管理工作流程

工作流程：

1. n8n_create_workflow({name, nodes, connections})
2. n8n_validate_workflow({id})
3. n8n_update_partial_workflow({id, operations: [...]})
4. 再次 n8n_validate_workflow({id})
5. n8n_update_partial_workflow({id, operations: [{type: "activateWorkflow"}]})

常見模式：迭代更新（平均每次編輯間隔 56 秒）

關鍵：建立工作流程時的節點 JSON 衛生

產生的節點 JSON 中有三種結構性錯誤會破壞 n8n UI，即使工作流程驗證通過：

1. 絕對不要發出帶有佔位符 ID 的 credentials 區塊。 假 ID 如 "id": "REPLACE_ME" 會讓憑證選擇器在 n8n UI 中永久停用且無法點擊（顯示「尚無憑證」）— 使用者必須從頭重建節點。如果你不知道真實的憑證 ID，完全省略 credentials 區塊；缺少區塊時會顯示正常的空白下拉選單，使用者可以點擊。請先使用 n8n_manage_credentials({action: "list"}) 探索真實的憑證 ID。

// ❌ 破壞憑證選擇器
"credentials": {"httpHeaderAuth": {"id": "REPLACE_ME", "name": "My API Key"}}

// ✅ 未知 ID → 省略 credentials 區塊；使用者在 UI 中選取
// ✅ 已知 ID（來自 n8n_manage_credentials 列表）→ 使用真實 ID

2. 為節點 id 產生 UUID v4 值 — 不要使用人類可讀的字串如 "http-list-node"。n8n 的前端使用節點 ID 進行表單綁定和憑證元件初始化；非 UUID 的 ID 會導致微妙的 UI 問題。

3. 為每個節點使用當前的 typeVersion — 透過 get_node 檢查，不要硬記版本（例如 httpRequest 目前是 4.4+，不是 4.2）。

---

關鍵：nodeType 格式

兩種不同格式用於不同工具！

格式 1：搜尋/驗證工具

// 使用 SHORT 前綴
"nodes-base.slack"
"nodes-base.httpRequest"
"nodes-base.webhook"
"nodes-langchain.agent"

使用此格式的工具：

• search_nodes（回傳此格式）
• get_node
• validate_node
• validate_workflow

格式 2：工作流程工具

// 使用 FULL 前綴
"n8n-nodes-base.slack"
"n8n-nodes-base.httpRequest"
"n8n-nodes-base.webhook"
"@n8n/n8n-nodes-langchain.agent"

使用此格式的工具：

• n8n_create_workflow
• n8n_update_partial_workflow

轉換

// search_nodes 回傳兩種格式
{
  "nodeType": "nodes-base.slack",          // 用於搜尋/驗證工具
  "workflowNodeType": "n8n-nodes-base.slack"  // 用於工作流程工具
}

---

常見錯誤

八個常見錯誤。其中兩個值得完整展示，因為它們會默默破壞結構：

// nodeType 前綴（搜尋/驗證工具使用 SHORT 形式）
get_node({nodeType: "slack"})              // ❌ 缺少前綴 → "Node not found"
get_node({nodeType: "n8n-nodes-base.slack"}) // ❌ FULL 前綴用於工作流程工具
get_node({nodeType: "nodes-base.slack"})     // ✅

// credentials 必須按類型巢狀包含 {id, name} — 不是扁平字串
updates: {credentials: "myApiKey"}                              // ❌
updates: {credentials: {httpHeaderAuth: {id: "abc123", name: "My API Key"}}}  // ✅

#	錯誤	修正
1	錯誤的 nodeType 格式	搜尋/驗證用 SHORT nodes-base.*；工作流程工具用 FULL n8n-nodes-base.*（見上方）
2	預設使用 detail: "full"	預設 standard 涵蓋 95%；需要時改用 docs/search_properties 而非 full
3	未指定驗證設定檔	明確傳入 profile: "runtime"（其他階段可用 minimal/ai-friendly/strict）
4	忽略自動清理	所有節點在任何更新時都會被清理（運算子結構、IF/Switch 元資料）；無法修復斷開的連線或分支數量不匹配
5	未使用智慧參數	使用 branch: "true" / case: 0 取代脆弱的 sourceIndex 計算
6	省略 intent	在 n8n_update_partial_workflow 上始終包含 intent 以獲得更好的回應
7	使用 parameters 而非 updates	updateNode 接受 updates: {...}，不是 parameters: {...}
8	錯誤的憑證格式	按類型巢狀包含 {id, name}（見上方）

每個錯誤的完整錯誤/正確範例：請參閱 VALIDATION_GUIDE.md → 常見錯誤。

---

工具使用模式

三種模式主導實際使用。每個模式的逐步範例位於參考指南中。

• 模式 1 — 節點探索（步驟間平均 18 秒）：search_nodes({query}) → get_node({nodeType, includeExamples: true})。請參閱 SEARCH_GUIDE.md。
• 模式 2 — 驗證迴圈（思考 23 秒，修正 58 秒）：validate_node({profile: "runtime"}) → 讀取 errors → 修正設定 → 再次驗證直到乾淨。請參閱 VALIDATION_GUIDE.md。
• 模式 3 — 工作流程編輯（99.0% 成功率，編輯間平均 56 秒）：迭代 n8n_update_partial_workflow（附帶 intent）→ n8n_validate_workflow → 最後 activateWorkflow。逐步建立，不要一次完成。請參閱 WORKFLOW_GUIDE.md。

---

詳細指南

節點探索工具

請參閱 SEARCH_GUIDE.md 了解：

• search_nodes
• 搭配詳細度層級的 get_node（minimal、standard、full）
• get_node 模式（info、docs、search_properties、versions）

驗證工具

請參閱 VALIDATION_GUIDE.md 了解：

• 驗證設定檔說明
• 搭配模式的 validate_node（minimal、full）
• validate_workflow 完整結構
• 自動清理系統
• 處理驗證錯誤

工作流程管理

請參閱 WORKFLOW_GUIDE.md 了解：

• n8n_create_workflow
• n8n_update_partial_workflow（19 種操作類型，包含 patchNodeField！）
• 智慧參數（branch、case）
• AI 連線類型（8 種）
• 工作流程啟用（activateWorkflow/deactivateWorkflow）
• n8n_deploy_template
• n8n_workflow_versions
• n8n_manage_credentials（憑證 CRUD + 結構探索）
• n8n_audit_instance（安全稽核）

範本、資料表與自助工具

請參閱 OPERATIONS_GUIDE.md 了解：

• search_templates / get_template / n8n_deploy_template 範例
• n8n_manage_datatable（完整動作、篩選條件、範例）
• tools_documentation、ai_agents_guide、n8n_health_check

---

範本使用

2,700 多個範本庫包含三個工具：search_templates（模式 query/by_nodes/by_task/by_metadata）、get_template（模式 structure/full）和 n8n_deploy_template（部署到你的執行個體，支援 autoFix/autoUpgradeVersions，回傳工作流程 ID + 所需憑證 + 已套用的修正）。

完整的搜尋/取得/部署範例請參閱 OPERATIONS_GUIDE.md。

---

資料表管理

n8n_manage_datatable 是用於從工作流程外部管理資料表與資料列的 MCP 工具（表格動作 createTable/listTables/getTable/updateTable/deleteTable；資料列動作 getRows/insertRows/updateRows/upsertRows/deleteRows，支援篩選、分頁和 dryRun）。不要與工作流程內的 nodes-base.dataTable 節點混淆，後者在執行期間讀寫資料列（請參閱 n8n-node-configuration → OPERATION_PATTERNS.md）。經驗法則：MCP 工具用於一次性設定表格，工作流程節點用於每次執行時讀寫。deleteRows 需要篩選條件；大量變更前請使用 dryRun: true。

所有動作、篩選條件和範例請參閱 OPERATIONS_GUIDE.md。

---

憑證管理

n8n_manage_credentials 是統一的憑證工具：動作 list、get、create、update、delete、getSchema。它絕不會回傳機密 — get/create/update 會移除 data 欄位。在 create 之前使用 getSchema 探索必填欄位。可選的 includeUsage: true 標記（用於 list/get）會反向掃描工作流程，並附加 usedIn: [{id, name, active}] + usageCount — 在刪除或輪換憑證前使用它來查看會影響哪些內容（它會觸發完整的客戶端掃描，上限 5000 個工作流程，排除已封存，失敗時降級為 usageScanError 欄位）。

所有動作、includeUsage 形狀、安全注意事項和安全刪除/輪換工作流程請參閱 WORKFLOW_GUIDE.md。

---

安全與稽核

n8n_audit_instance 結合了 n8n 的內建稽核（類別 credentials/database/nodes/instance/filesystem）與自訂深度掃描（hardcoded_secrets、unauthenticated_webhooks、error_handling、data_retention）。所有參數皆為選填：categories、includeCustomScan（預設 true）、customChecks、daysAbandonedWorkflow。偵測到的機密會被遮罩（前 6 碼 + 後 4 碼）。輸出為可操作的 markdown 報告 — 摘要表格、按工作流程分類的發現，以及分為可自動修復/需審查/需使用者操作的補救手冊。

兩種掃描方式、範例和完整的補救類型請參閱 WORKFLOW_GUIDE.md。

---

自助工具

• tools_documentation() — 所有工具的概覽；tools_documentation({topic, depth: "full"}) 用於特定工具。程式碼節點指南可透過主題 javascript_code_node_guide / python_code_node_guide 取得。
• AI 代理指南 — tools_documentation({topic: "ai_agents_guide", depth: "full"})（無獨立工具）；回傳架構、連線、工具、驗證、最佳實務。
• n8n_health_check() — 快速檢查；n8n_health_check({mode: "diagnostic"}) 回傳狀態、環境變數、工具狀態、API 連線能力。

範例請參閱 OPERATIONS_GUIDE.md。

---

工具可用性

始終可用（無需 n8n API）：

• search_nodes、get_node
• validate_node、validate_workflow
• search_templates、get_template
• tools_documentation（包含 ai_agents_guide 主題）

需要 n8n API（N8N_API_URL + N8N_API_KEY）：

• n8n_create_workflow
• n8n_update_partial_workflow、n8n_update_full_workflow
• n8n_validate_workflow（依 ID）
• n8n_list_workflows、n8n_get_workflow、n8n_delete_workflow
• n8n_test_workflow
• n8n_executions
• n8n_deploy_template
• n8n_workflow_versions
• n8n_autofix_workflow
• n8n_manage_datatable
• n8n_manage_credentials
• n8n_audit_instance

如果 API 工具不可用，請使用範本和僅驗證的工作流程。

---

統一工具參考

• get_node — 詳細度層級（minimal ~200 tok / standard ~1-2K，建議使用 / full ~3-8K，謹慎使用）和模式（info 預設、docs、search_properties + propertyQuery、versions、compare、breaking、migrations）。深入探討請參閱 SEARCH_GUIDE.md。
• validate_node — 模式 full（預設，包含錯誤/警告/建議）和 minimal（必填欄位檢查）；設定檔 minimal/runtime（預設，建議使用）/ai-friendly/strict。深入探討請參閱 VALIDATION_GUIDE.md。

---

效能特性

工具	回應時間	酬載大小
search_nodes	<20ms	小
get_node (standard)	<10ms	~1-2KB
get_node (full)	<100ms	3-8KB
validate_node (minimal)	<50ms	小
validate_node (full)	<100ms	中
validate_workflow	100-500ms	中
n8n_manage_credentials	50-500ms	小-中
n8n_audit_instance	500-5000ms	大
n8n_create_workflow	100-500ms	中
n8n_update_partial_workflow	50-200ms	小
n8n_deploy_template	200-500ms	中

---

最佳實務

應做

• 對於簡單工作流程（<=5 個節點），直接使用 MCP 工具 — 不要過度設計調查
• 使用 patchNodeField 對程式碼節點內容進行精確編輯，而非取代整個節點
• 大多數情況下使用 get_node({detail: "standard"})
• 明確指定驗證設定檔（profile: "runtime"）
• 使用智慧參數（branch、case）以提升清晰度
• 在工作流程更新中包含 intent 參數
• 遵循 search → get_node → validate 工作流程
• 迭代工作流程（平均每次編輯間隔 56 秒）
• 每次重大變更後進行驗證
• 使用 includeExamples: true 取得真實設定
• 使用 n8n_deploy_template 快速入門

不應做

• 除非必要，否則不要使用 detail: "full"（浪費 token）
• 不要忘記 nodeType 前綴（nodes-base.*）
• 不要跳過驗證設定檔
• 不要嘗試一次建立工作流程（要迭代！）
• 不要忽略自動清理行為
• 不要在搜尋/驗證工具中使用完整前綴（n8n-nodes-base.*）
• 建立工作流程後不要忘記啟用

---

總結

最重要的事項：

1. 使用 get_node 搭配 detail: "standard"（預設）— 涵蓋 95% 的使用案例
2. nodeType 格式不同：nodes-base.*（搜尋/驗證）vs n8n-nodes-base.*（工作流程）
3. 指定驗證設定檔（建議使用 runtime）
4. 使用智慧參數（branch="true"、case=0）
5. 在工作流程更新中包含 intent 參數
6. 自動清理會在更新期間對所有節點執行
7. 工作流程可透過 API 啟用（activateWorkflow 操作）
8. 工作流程應迭代建立（平均每次編輯間隔 56 秒）
9. 資料表使用 n8n_manage_datatable 管理（CRUD + 篩選）
10. 憑證使用 n8n_manage_credentials 管理（CRUD + 結構探索）
11. 安全稽核透過 n8n_audit_instance 進行（內建 + 自訂深度掃描）
12. AI 代理指南可透過 tools_documentation({topic: "ai_agents_guide", depth: "full"}) 取得

常見工作流程：

1. search_nodes → 尋找節點
2. get_node → 了解設定
3. validate_node → 檢查設定
4. n8n_create_workflow → 建立
5. n8n_validate_workflow → 驗證
6. n8n_update_partial_workflow → 迭代
7. activateWorkflow → 上線！

詳細資訊請參閱：

• SEARCH_GUIDE.md - 節點探索
• VALIDATION_GUIDE.md - 設定驗證 + 常見錯誤
• WORKFLOW_GUIDE.md - 工作流程管理
• OPERATIONS_GUIDE.md - 範本、資料表、自助工具

---

相關技能：

• n8n Expression Syntax - 在工作流程欄位中撰寫表達式
• n8n Workflow Patterns - 來自範本的架構模式
• n8n Validation Expert - 解讀驗證錯誤
• n8n Node Configuration - 特定操作的需求
• n8n Code JavaScript - 在程式碼節點中撰寫 JavaScript
• n8n Code Python - 在程式碼節點中撰寫 Python