n8n-mcp-tools-expert

n8n MCP ツールのエキスパートガイド

ワークフローの構築に n8n-mcp MCP サーバーのツールを使用するためのマスターガイドです。

---

ツールのカテゴリ

n8n-mcp には、以下のカテゴリに整理された 40 以上のツールがあります。

1. ノードの検索 → SEARCH_GUIDE.md
2. 設定の検証 → VALIDATION_GUIDE.md
3. ワークフロー管理 → WORKFLOW_GUIDE.md
4. テンプレートライブラリ - 2,653 件の実際のワークフローを検索してアクセス
5. ドキュメント - ツールとノードのドキュメントを取得

---

クイックリファレンス

最もよく使われるツール（成功率順）

ツール	使用する場面	成功率	速度
search_nodes	キーワードでノードを検索するとき	99.9%	<20ms
get_node_essentials	ノードの操作を理解するとき	91.7%	<10ms
validate_node_operation	設定を確認するとき	変動	<100ms
n8n_create_workflow	ワークフローを作成するとき	96.8%	100-500ms
n8n_update_partial_workflow	ワークフローを編集するとき（最もよく使われます！）	99.0%	50-200ms
validate_workflow	ワークフロー全体を確認するとき	95.5%	100-500ms

---

ツール選択ガイド

適切なノードを見つける

ワークフロー：

1. search_nodes({query: "keyword"})
2. get_node_essentials({nodeType: "nodes-base.name"})
3. [Optional] get_node_documentation({nodeType: "nodes-base.name"})

例：

// Step 1: Search
search_nodes({query: "slack"})
// Returns: nodes-base.slack

// Step 2: Get details (18s avg between steps)
get_node_essentials({nodeType: "nodes-base.slack"})
// Returns: operations, properties, examples

一般的なパターン：検索 → essentials（平均18秒）

設定を検証する

ワークフロー：

1. validate_node_minimal({nodeType, config: {}}) - Check required fields
2. validate_node_operation({nodeType, config, profile: "runtime"}) - Full validation
3. [Repeat] Fix errors, validate again

一般的なパターン：検証 → 修正 → 検証（検討に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}) again

一般的なパターン：反復的な更新（編集間の平均56秒）

---

重要：nodeType の形式

ツールによって異なる2種類の形式があります！

形式1：検索／検証ツール

// Use SHORT prefix
"nodes-base.slack"
"nodes-base.httpRequest"
"nodes-base.webhook"
"nodes-langchain.agent"

この形式を使うツール：

• search_nodes（この形式を返します）
• get_node_essentials
• get_node_info
• validate_node_minimal
• validate_node_operation
• get_property_dependencies

形式2：ワークフローツール

// Use FULL prefix
"n8n-nodes-base.slack"
"n8n-nodes-base.httpRequest"
"n8n-nodes-base.webhook"
"@n8n/n8n-nodes-langchain.agent"

この形式を使うツール：

• n8n_create_workflow
• n8n_update_partial_workflow
• list_node_templates

変換

// search_nodes returns BOTH formats
{
  "nodeType": "nodes-base.slack",          // For search/validate tools
  "workflowNodeType": "n8n-nodes-base.slack"  // For workflow tools
}

---

よくある間違い

❌ 間違い1：nodeType の形式が違う

問題：「Node not found」エラー

❌ get_node_essentials({nodeType: "slack"})  // Missing prefix
❌ get_node_essentials({nodeType: "n8n-nodes-base.slack"})  // Wrong prefix

✅ get_node_essentials({nodeType: "nodes-base.slack"})  // Correct!

❌ 間違い2：get_node_essentials の代わりに get_node_info を使う

問題：失敗率が20％で、応答が遅く、ペイロードが非常に大きい

❌ get_node_info({nodeType: "nodes-base.slack"})
// Returns: 100KB+ data, 20% chance of failure

✅ get_node_essentials({nodeType: "nodes-base.slack"})
// Returns: 5KB focused data, 91.7% success, <10ms

get_node_info を使う場面：

• 複雑な設定の問題をデバッグするとき
• プロパティスキーマ全体が必要なとき
• 高度な機能を調べるとき

より良い代替手段：

1. get_node_essentials - 操作一覧を取得する場合
2. get_node_documentation - 読みやすいドキュメントを取得する場合
3. search_node_properties - 特定のプロパティを検索する場合

❌ 間違い3：検証プロファイルを使わない

問題：誤検知が多すぎる、または実際のエラーを見逃す

プロファイル：

• minimal - 必須フィールドのみ（高速、寛容）
• runtime - 値と型（デプロイ前に推奨）
• ai-friendly - 誤検知を減らす（AI の設定向け）
• strict - 最大限の検証（本番環境向け）

❌ validate_node_operation({nodeType, config})  // Uses default

✅ validate_node_operation({nodeType, config, profile: "runtime"})  // Explicit

❌ 間違い4：自動サニタイズを無視する

発生すること：ワークフローを更新すると、すべてのノードがサニタイズされます

自動修正：

• 二項演算子（equals、contains）→ singleValue を削除
• 単項演算子（isEmpty、isNotEmpty）→ singleValue: true を追加
• IF／Switch ノード → 不足しているメタデータを追加

修正できないもの：

• 破損した接続
• ブランチ数の不一致
• 矛盾した破損状態

// After ANY update, auto-sanitization runs on ALL nodes
n8n_update_partial_workflow({id, operations: [...]})
// → Automatically fixes operator structures

❌ 間違い5：スマートパラメーターを使わない

問題：複数の出力を持つノードで、複雑な sourceIndex の計算が必要になる

従来の方法（手動）：

// IF node connection
{
  type: "addConnection",
  source: "IF",
  target: "Handler",
  sourceIndex: 0  // Which output? Hard to remember!
}

新しい方法（スマートパラメーター）：

// IF node - semantic branch names
{
  type: "addConnection",
  source: "IF",
  target: "True Handler",
  branch: "true"  // Clear and readable!
}

{
  type: "addConnection",
  source: "IF",
  target: "False Handler",
  branch: "false"
}

// Switch node - semantic case numbers
{
  type: "addConnection",
  source: "Switch",
  target: "Handler A",
  case: 0
}

---

ツールの使用パターン

パターン1：ノードの検索（最も一般的）

一般的なワークフロー：ステップ間の平均18秒

// Step 1: Search (fast!)
const results = await search_nodes({
  query: "slack",
  mode: "OR",  // Default: any word matches
  limit: 20
});
// → Returns: nodes-base.slack, nodes-base.slackTrigger

// Step 2: Get details (~18s later, user reviewing results)
const details = await get_node_essentials({
  nodeType: "nodes-base.slack",
  includeExamples: true  // Get real template configs
});
// → Returns: operations, properties, metadata

パターン2：検証ループ

一般的なサイクル：検討に23秒、修正に58秒

// Step 1: Validate
const result = await validate_node_operation({
  nodeType: "nodes-base.slack",
  config: {
    resource: "channel",
    operation: "create"
  },
  profile: "runtime"
});

// Step 2: Check errors (~23s thinking)
if (!result.valid) {
  console.log(result.errors);  // "Missing required field: name"
}

// Step 3: Fix config (~58s fixing)
config.name = "general";

// Step 4: Validate again
await validate_node_operation({...});  // Repeat until clean

パターン3：ワークフローの編集

最もよく使われる更新ツール：成功率99.0％、編集間の平均56秒

// Iterative workflow building (NOT one-shot!)
// Edit 1
await n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{type: "addNode", node: {...}}]
});

// ~56s later...

// Edit 2
await n8n_update_partial_workflow({
  id: "workflow-id",
  operations: [{type: "addConnection", source: "...", target: "..."}]
});

// ~56s later...

// Edit 3 (validation)
await n8n_validate_workflow({id: "workflow-id"});

---

詳細ガイド

ノード検索ツール

SEARCH_GUIDE.md を参照してください。

• search_nodes（成功率 99.9%）
• get_node_essentials と get_node_info の比較
• カテゴリー別の list_nodes
• 特定のフィールドを検索する search_node_properties

検証ツール

VALIDATION_GUIDE.md を参照してください。

• 検証プロファイルの説明
• validate_node_minimal と validate_node_operation の比較
• validate_workflow による完全な構造検証
• 自動サニタイズシステム
• 検証エラーへの対処

ワークフロー管理

WORKFLOW_GUIDE.md を参照してください。

• n8n_create_workflow
• n8n_update_partial_workflow（15 種類の操作！）
• スマートパラメーター（branch、case）
• AI 接続タイプ（8 種類）
• cleanStaleConnections による復旧

---

テンプレートの使用方法

テンプレートの検索

// Search by keyword
search_templates({
  query: "webhook slack",
  limit: 20
});
// → Returns: 1,085 templates with metadata

// Get template details
get_template({
  templateId: 2947,  // Weather to Slack
  mode: "structure"  // or "full" for complete JSON
});

テンプレートのメタデータ

テンプレートには次の情報が含まれます。

• 複雑さ（シンプル、中程度、複雑）
• セットアップ時間の見積もり
• 必要なサービス
• カテゴリーとユースケース
• 閲覧数（人気度）

---

セルフヘルプツール

ツールのドキュメントを取得

// List all tools
tools_documentation()

// Specific tool details
tools_documentation({
  topic: "search_nodes",
  depth: "full"
})

ヘルスチェック

// Verify MCP server connectivity
n8n_health_check()
// → Returns: status, features, API availability, version

データベース統計

get_database_statistics()
// → Returns: 537 nodes, 270 AI tools, 2,653 templates

---

ツールの利用可否

常に利用可能（n8n API は不要）：

• search_nodes、list_nodes、get_node_essentials ✅
• validate_node_minimal、validate_node_operation ✅
• validate_workflow、get_property_dependencies ✅
• search_templates、get_template、list_tasks ✅
• tools_documentation、get_database_statistics ✅

n8n API が必要（N8N_API_URL + N8N_API_KEY）：

• n8n_create_workflow ⚠️
• n8n_update_partial_workflow ⚠️
• n8n_validate_workflow（ID 指定）⚠️
• n8n_list_workflows、n8n_get_workflow ⚠️
• n8n_trigger_webhook_workflow ⚠️

API ツールを利用できない場合は、テンプレートと検証のみのワークフローを使用してください。

---

パフォーマンス特性

ツール	応答時間	ペイロードサイズ	信頼性
search_nodes	<20ms	小	99.9%
list_nodes	<20ms	小	99.6%
get_node_essentials	<10ms	~5KB	91.7%
get_node_info	変動	100KB+	80% ⚠️
validate_node_minimal	<100ms	小	97.4%
validate_node_operation	<100ms	中	変動
validate_workflow	100-500ms	中	95.5%
n8n_create_workflow	100-500ms	中	96.8%
n8n_update_partial_workflow	50-200ms	小	99.0%

---

ベストプラクティス

✅ 推奨事項

• get_node_info より get_node_essentials を使用する（91.7% 対 80%）
• 検証プロファイルを明示的に指定する
• 明確にするため、スマートパラメーター（branch、case）を使用する
• search → essentials → validate のワークフローに従う
• ワークフローを反復的に編集する（編集間隔は平均 56 秒）
• 大きな変更を加えるたびに検証する
• 実際の設定には includeExamples: true を使用する

❌ 禁止事項

• 必要な場合を除き、get_node_info を使用しない（失敗率 20%！）
• nodeType のプレフィックス（nodes-base.*）を忘れない
• 検証プロファイルを省略しない（「runtime」を使用する）
• ワークフローを一度で完成させようとしない（反復的に進める！）
• 自動サニタイズの動作を無視しない
• 検索ツールで完全なプレフィックス（n8n-nodes-base.*）を使用しない

概要

最重要事項：

1. get_node_info ではなく get_node_essentials を使用してください（5KB 対 100KB、91.7％ 対 80％）
2. nodeType の形式は異なります：nodes-base.*（検索）と n8n-nodes-base.*（ワークフロー）
3. 検証プロファイルを指定してください（runtime を推奨）
4. スマートパラメーターを使用してください（branch="true"、case=0）
5. 更新時には、すべてのノードで自動サニタイズが実行されます
6. ワークフローは反復的に構築されます（編集間の平均時間は 56 秒）

一般的なワークフロー：

1. search_nodes → ノードを検索
2. get_node_essentials → 設定を把握
3. validate_node_operation → 設定を確認
4. n8n_create_workflow → 構築
5. n8n_validate_workflow → 検証
6. n8n_update_partial_workflow → 反復

詳細については、以下を参照してください。

• SEARCH_GUIDE.md - ノードの検出
• VALIDATION_GUIDE.md - 設定の検証
• WORKFLOW_GUIDE.md - ワークフローの管理

---

関連スキル：

• n8n Expression Syntax - ワークフローのフィールドに式を記述
• n8n Workflow Patterns - テンプレートに基づくアーキテクチャパターン
• n8n Validation Expert - 検証エラーの解釈
• n8n Node Configuration - 操作固有の要件