n8n Workflow Builder MCP Server

---

🎯 これは何ですか？

n8n Workflow Builder MCP Server は、会話型 AI を通じて n8n ワークフローを作成、管理できるようにし、ワークフロー自動化を変革します。手作業での JSON 編集や複雑な UI 操作はもう必要ありません。必要なことを自然言語で説明するだけで、AI が構築します。

解決する課題

• ❌ 手作業でのワークフロー構築には時間がかかり、エラーも発生しやすい
• ❌ 複雑な JSON 編集には高度な技術知識が必要
• ❌ IDE と n8n UI の切り替えによって開発の流れが中断される
• ❌ 複数の n8n 環境（開発、ステージング、本番）の管理は面倒

解決策

• ✅ Claude AI または Cursor IDE を使い、会話形式でワークフローを構築
• ✅ 自然言語インターフェース — 平易な英語でワークフローを説明
• ✅ 複数インスタンスのサポート — 1 か所から開発、ステージング、本番環境を管理
• ✅ 強力な 17 個のツール — ワークフローのライフサイクルを完全に管理
• ✅ IDE 上で作業を継続 — コンテキストの切り替えは不要

---

✨ 主な機能

🤖 AI 搭載のワークフロー作成 必要なことを説明するだけで、複雑な n8n ワークフローを作成できます。Claude AI と Cursor IDE が意図を理解し、本番環境ですぐに使えるワークフローを生成します。 🌍 複数インスタンスの管理 インテリジェントなインスタンスルーティングを備えた単一の MCP サーバーから、複数の n8n 環境（本番、ステージング、開発）をシームレスに管理できます。 🛠️ 17 個の包括的なツール ワークフローのライフサイクルを包括的にカバーします。 8 個のワークフローツール — 作成、更新、削除、有効化、実行 4 個の実行ツール — 実行の監視、再試行、分析 5 個のタグツール — ワークフローの整理と分類 6 個の認証情報ツール（Epic 2） — 認証情報を安全に管理

💬 自然言語インターフェース JSON 編集は不要です。たとえば、次のようにワークフローを構築できます。 「顧客のメールアドレスを検証し、Slack 通知を送信して、データを PostgreSQL に保存する Webhook ワークフローを作成して」 🔒 セキュリティを重視した設計 認証情報の保護機能を内蔵 API キーの暗号化 安全な複数インスタンス構成 ログに機密データが含まれることはありません 📚 充実したドキュメント ガイドとチュートリアルを含む 38 ページ以上のドキュメント インタラクティブな例とワークフローパターン トラブルシューティングガイドと FAQ すべてのツールを網羅した API リファレンス

---

🚀 クイックスタート

前提条件

• Node.js v14+（v18+ を推奨）
• npm v7+
• API アクセスが可能な n8n インスタンス（n8n v1.82.3+ でテスト済み）
• Claude Desktop または Cursor IDE

インストール

# Install globally via npm
npm install -g @kernel.salacoste/n8n-workflow-builder

# Verify installation
npx @kernel.salacoste/n8n-workflow-builder --version

設定

オプション 1：複数インスタンス（推奨）

プロジェクトのルートに .config.json を作成します。

{
  "environments": {
    "production": {
      "n8n_host": "https://n8n.example.com",
      "n8n_api_key": "your_production_api_key"
    },
    "staging": {
      "n8n_host": "https://staging.n8n.example.com",
      "n8n_api_key": "your_staging_api_key"
    },
    "development": {
      "n8n_host": "http://localhost:5678",
      "n8n_api_key": "your_dev_api_key"
    }
  },
  "defaultEnv": "development"
}

オプション 2：単一インスタンス（後方互換）

.env ファイルを作成します。

N8N_HOST=https://your-n8n-instance.com
N8N_API_KEY=your_api_key

Claude Desktop との統合

Claude Desktop の設定に追加します（macOS の場合は ~/Library/Application Support/Claude/claude_desktop_config.json）。

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"]
    }
  }
}

Claude Desktop を再起動すれば、準備完了です！🎉

Cursor IDE との統合

ワークスペースの .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "n8n-workflow-builder": {
      "command": "npx",
      "args": ["@kernel.salacoste/n8n-workflow-builder"]
    }
  }
}

---

📖 ドキュメント全編

充実したドキュメントサイトをご覧ください。

🌐 ドキュメント全編

クイックリンク

セクション	説明
🚀 クイックスタートチュートリアル	5 分で最初のワークフローを作成
📦 インストールガイド	詳細なセットアップ手順
🔧 設定	マルチインスタンスと環境のセットアップ
🛠️ API リファレンス	ツールの完全なドキュメント
🏗️ マルチインスタンスのセットアップ	複数の n8n 環境を管理
💡 使用パターン	ベストプラクティスと会話パターン
🐛 トラブルシューティング	よくある問題と解決方法

---

🎨 使用例

例 1：Webhook ワークフローを作成する

あなた：

ステージング環境に、次の処理を行う Webhook ワークフローを作成してください。

• /customer-signup で POST リクエストを受信する
• メールアドレスと名前のフィールドを検証する
• Gmail でウェルカムメールを送信する
• 顧客情報を PostgreSQL に保存する

Claude： ✅ 検証、メール、データベースのノードを含む完全なワークフローを作成します

例 2：マルチインスタンスのワークフロー管理

あなた：

過去 7 日間に実行されていない、本番環境のアクティブなワークフローをすべて一覧表示してください

Claude： 📊 本番環境を分析し、古くなったワークフローを特定します

例 3：失敗した実行をデバッグする

あなた：

本番環境のワークフロー 456 をデバッグしてください。エラーが発生して失敗し続けています

Claude： 🔍 実行履歴を取得し、根本原因を特定して、修正方法を提案します

例 4：認証情報の管理

あなた：

OAuth2 認証情報のスキーマを表示してから、Google Sheets API の認証情報の作成を手伝ってください

Claude： 🔐 認証情報のスキーマを取得し、安全な認証情報の作成を案内します

---

🛠️ MCP ツールリファレンス

ワークフロー管理（8 ツール）

ツール	説明	使用例
list_workflows	フィルターを指定してすべてのワークフローを一覧表示	「本番環境のアクティブなワークフローを表示してください」
get_workflow	ワークフローの詳細情報をすべて取得	「ステージング環境のワークフロー 123 を取得してください」
create_workflow	新しいワークフローをゼロから作成	「毎日のレポートを作成するワークフローを作成してください」
update_workflow	既存のワークフローを変更	「ワークフロー 456 にエラー処理を追加してください」
delete_workflow	ワークフローを削除	「ワークフロー 789 を削除してください」
activate_workflow	ワークフローの実行を有効化	「ワークフロー 123 を有効化してください」
deactivate_workflow	ワークフローの実行を無効化	「ワークフロー 456 を無効化してください」
execute_workflow	ワークフローを手動で実行	「テストデータを使ってワークフロー 789 を実行してください」

実行管理（4 ツール）

ツール	説明	使用例
list_executions	フィルターを指定して実行履歴を表示	「今日の失敗した実行を表示してください」
get_execution	実行の詳細情報を取得	「実行 9876 の詳細を取得してください」
delete_execution	実行記録を削除	「古いテスト実行を削除してください」
retry_execution	失敗したワークフローの実行を再試行	「実行 9876 を再試行してください」

タグ管理（5 つのツール）

ツール	説明	使用例
list_tags / get_tags	すべてのワークフロータグを取得します	「すべてのワークフロータグを表示」
get_tag	指定したタグの情報を取得します	「'email-automation' のタグの詳細を取得」
create_tag	ワークフローを整理するタグを作成します	「'customer-workflows' タグを作成」
update_tag	タグ情報を変更します	「タグ名を 'legacy-workflows' に変更」
delete_tag	ワークフロータグを削除します	「'deprecated' タグを削除」

認証情報管理（6 つのツール - Epic 2）

ツール	説明	使用例
get_credential_schema	認証情報の種類に対応する JSON スキーマを取得します	「httpBasicAuth のスキーマを表示」
list_credentials	セキュリティに関するガイダンス（n8n API によりブロックされています）	「認証情報の一覧に関するガイダンスを表示」
get_credential	セキュリティに関するガイダンス（n8n API によりブロックされています）	「認証情報の取得に関するガイダンスを表示」
create_credential	スキーマ検証付きで認証情報を作成します	「Gmail OAuth2 認証情報を作成」
update_credential	不変性に関するガイダンス（DELETE + CREATE）	「認証情報の更新に関するガイダンスを表示」
delete_credential	認証情報を完全に削除します	「認証情報 123 を削除」

---

🏗️ マルチインスタンスアーキテクチャ

インテリジェントなルーティングで、複数の n8n 環境を管理できます。

┌─────────────────────────────────────┐
│   MCP Server (Single Instance)     │
├─────────────────────────────────────┤
│                                     │
│  ┌──────────┐  ┌──────────┐       │
│  │ ConfigLoader│ EnvironmentMgr   │
│  └──────────┘  └──────────┘       │
│         │            │             │
│         ▼            ▼             │
│  ┌─────────────────────────┐      │
│  │   Instance Routing      │      │
│  └─────────────────────────┘      │
│         │                          │
└─────────┼──────────────────────────┘
          │
    ┌─────┴─────┬─────────────┬──────────────┐
    │           │             │              │
    ▼           ▼             ▼              ▼
┌────────┐  ┌────────┐   ┌────────┐    ┌────────┐
│  Dev   │  │Staging │   │  Prod  │    │Custom  │
│ n8n    │  │  n8n   │   │  n8n   │    │  n8n   │
└────────┘  └────────┘   └────────┘    └────────┘

メリット:

• ✅ 1 つの MCP サーバーですべての環境を管理できます
• ✅ コンテキストに基づいてインスタンスを自動的にルーティングします
• ✅ 環境ごとに個別の API キーを使用できます
• ✅ 会話中に環境を簡単に切り替えられます

---

🎯 使用例

🚀 開発ワークフロー

1. 開発環境で構築: ワークフローをローカルで作成し、テストします
2. ステージング環境にデプロイ: QA 環境で検証します
3. 本番環境に昇格: 確信を持ってデプロイします

📊 運用とモニタリング

• 環境をまたいで実行ステータスを監視します
• 詳細な分析で失敗したワークフローをデバッグします
• ワークフローのパフォーマンスと信頼性を追跡します

🔄 ワークフローの移行

• あるインスタンスからワークフローをエクスポートします
• 自動調整を行い、別のインスタンスにインポートします
• 環境をまたいで一括操作を実行します

📝 ドキュメントと学習

• ワークフローのドキュメントを自動生成します
• AI によるガイダンスを通じて n8n のパターンを学習します
• ワークフローの例やテンプレートを確認します

---

🔒 セキュリティとベストプラクティス

認証情報の保護

• ✅ .config.json は .gitignore により Git から自動的に除外されます
• ✅ API キーはログに記録されません（最初の 20 文字のみ表示されます）
• ✅ 認証情報は n8n API によって暗号化されます
• ✅ npm パッケージに機密データは含まれません

マルチインスタンスのセキュリティ

• ✅ 環境ごとに個別の API キーを使用します
• ✅ 本番環境のキーは開発環境から分離されています
• ✅ API 呼び出しの前にインスタンスを検証します

安全な操作

⚠️ IMPORTANT: Be careful with destructive operations!

- Always test in development first
- Use get_workflow to backup before modifications
- Review workflow details before deletion
- Enable debug mode for troubleshooting

---

🐛 トラブルシューティング

よくある問題

MCP サーバーへの接続に失敗する

症状： Claude/Cursor で n8n ツールが見つかりません

解決方法：

1. Claude Desktop / Cursor IDE を再起動します
2. claude_desktop_config.json / .cursor/mcp.json の構文を確認します
3. n8n インスタンスにアクセスできることを確認します
4. デバッグモードを有効にします：環境変数に DEBUG=true を設定します

デバッグガイド全文

n8n API の呼び出し時に 404 エラーが発生する

症状： 「Request failed with status code 404」

解決方法：

1. n8n_host にベース URL（例：https://n8n.example.com）を指定していることを確認します
2. /api/v1 のサフィックスは含めないでください（サーバーが自動的に追加します）
3. n8n API キーに適切な権限があることを確認します
4. 接続をテストします：curl https://your-n8n-instance.com/api/v1/workflows

設定ガイド

ワークフローの有効化に失敗する

症状： 「Workflow cannot be activated without valid trigger」

解決方法：

1. ワークフローに少なくとも 1 つのトリガーノード（Webhook、スケジュールなど）があることを確認します
2. manualTrigger は n8n API v1.82.3 では認識されません
3. トリガーがない場合、サーバーが有効なトリガーを自動的に追加します

エラーリファレンス

ヘルプを利用する

• 📚 トラブルシューティングガイド全文
• 🐛 問題を報告
• 💬 GitHub ディスカッション

---

📊 新機能

バージョン 0.9.3（最新）- セキュリティとドキュメント

• 🔒 セキュリティ修正： ログファイルが npm に公開されないように修正
• 📦 パッケージの最適化： サイズを 699KB から 653KB に削減
• 📚 ドキュメントの強化： バッジを追加し、npm メタデータを改善
• ✅ API キーのローテーション： セキュリティ対策を更新

バージョン 0.9.0 - MCP プロトコルへの準拠

• ✅ MCP 通知ハンドラーを完全にサポート
• ✅ 「Method 'notifications/initialized' not found」エラーを修正
• 📦 パッケージサイズを最適化： 1.3MB → 278KB
• 🏗️ インテリジェントなルーティングを備えたマルチインスタンスアーキテクチャ
• 🔐 スキーマ検証による認証情報管理の強化

エピック 2 完了（13/13 ストーリー）- 高度な API 実装

• ✅ 17 個の MCP ツールを実装（ワークフロー 8 個 + 実行 4 個 + タグ 5 個 + 認証情報 6 個）
• ✅ すべての実装でテスト成功率 100％
• ✅ 包括的なサンプルを含む12,000 行以上のドキュメント
• ✅ バグゼロの本番環境対応品質

変更履歴全文を見る

---

🗺️ ロードマップ

✅ 完了

• ワークフローのコア CRUD 操作
• 実行の管理と監視
• タグベースのワークフロー整理
• マルチインスタンスアーキテクチャ
• 認証情報のライフサイクル管理
• 包括的なドキュメントサイト（38 ページ以上）
• CI/CD を使用した GitHub Pages へのデプロイ

🚧 作業中

• ワークフローテンプレートライブラリ
• エラー復旧パターンの強化
• 大規模ワークフローのパフォーマンス最適化
• 高度なフィルタリングおよび検索機能

🔮 計画中

• ビジュアルワークフローエディターとの統合
• ワークフローのバージョン管理とロールバック
• 共同でのワークフロー開発
• 高度な分析とインサイト
• ワークフローのマーケットプレイスと共有

機能を提案

---

🤝 コントリビューション

コントリビューションを歓迎します！以下の方法でご協力いただけます。

貢献方法

• 🐛 バグを報告する： Issueを作成
• 💡 機能を提案する： ディスカッションを開始
• 📖 ドキュメントを改善する： ドキュメントの改善を提出する
• 🔧 プルリクエストを送信する： バグを修正するか、機能を追加する

開発環境のセットアップ

# Clone repository
git clone https://github.com/salacoste/mcp-n8n-workflow-builder.git
cd mcp-n8n-workflow-builder

# Install dependencies
npm install

# Build project
npm run build

# Run tests
npm test

# Start development server
npm run dev

コード規約

• ✅ 型安全性のためのTypeScript
• ✅ コード品質を保つためのESLint
• ✅ フォーマットのためのPrettier
• ✅ テストのためのJest
• ✅ Conventional Commits

貢献ガイド

---

📄 ライセンス

このプロジェクトはMIT Licenseの下でライセンスされています。詳細はLICENSEファイルをご覧ください。

これが意味すること

• ✅ 商用利用が可能です
• ✅ 改変が可能です
• ✅ 再配布が可能です
• ✅ 私的利用が可能です
• ⚠️ 保証はありません
• ⚠️ 一切の責任を負いません

ライセンスの詳細

---

🙏 謝辞

以下を使用して構築されています：

• 🤖 Claude AI - AIを活用した開発支援
• 🔧 n8n - ワークフロー自動化プラットフォーム
• 🔌 Model Context Protocol - AI統合標準
• 📝 TypeScript - 型安全な開発
• 📚 MkDocs Material - ドキュメントフレームワーク

特に感謝します：

• 素晴らしい自動化プラットフォームを開発したn8nチーム
• Claude AIとMCPを開発したAnthropicチーム
• フィードバックを寄せてくださるすべての貢献者とユーザー

---

📞 お問い合わせ

• 🌐 ドキュメント： https://salacoste.github.io/mcp-n8n-workflow-builder/
• 📦 npmパッケージ： https://www.npmjs.com/package/@kernel.salacoste/n8n-workflow-builder
• 💻 GitHub： https://github.com/salacoste/mcp-n8n-workflow-builder
• 🐛 Issue： https://github.com/salacoste/mcp-n8n-workflow-builder/issues
• 💬 ディスカッション： https://github.com/salacoste/mcp-n8n-workflow-builder/discussions

---