FoundryVTT MCP サーバー

Foundry Virtual Tabletop (FoundryVTT) のための、包括的かつ本番運用グレードの Model Context Protocol (MCP) サーバーです。

このサーバーは、AI アシスタント（Claude Desktop、Claude Code、Oh My Pi、VS Code、Cursor など）が FoundryVTT 内で完全な能力を持つ自律的な 共同 GM および GM アシスタント として動作することを可能にします。ゲームメカニクス、アクター、アイテム、トークン、戦闘エンカウンター、キャンバス配置物（壁、光源、音、テンプレート、描画、ノート、タイル）、プレイリスト、マクロ、ロールテーブル、コンペンディウム、ワールド設定、ライブキャンバスレンダリングにわたる完全な読み取り・書き込みアクセスを提供します。

🌟 主要なハイライトと機能（111 ツール）

• 👁️ リアルタイムイベントストリームとアクティビティログ（watch_events）: Socket.IO の modifyDocument とコンパニオンブリッジのプッシュによる、ポーリング不要のイベント認識。AI DM エージェントは、カーソル指定ストリーム（cursor、waitMs、excludeSelf、types、sceneId）でロングポーリングし、プレイヤーがチャット、トークン移動、戦闘進行、ドアの切り替え、ターゲット選択を行ったときに即座に反応できます。

• 🎲 ゲームメカニクスとインタラクティブチャット: 標準または複雑なドロップ/キープ記法（4d6kh3、1d20r1）でダイスをロール。コンパニオンブリッジを介して、インタラクティブでクリック可能なチャットカードを Foundry のチャットログに直接ロールして投稿できます（roll_and_post）。

• 🗺️ 完全なキャンバスと空間制御: すべてのキャンバス配置物タイプの作成、検査、更新、削除が可能です。

  • シーンリージョン（v12+）: 幾何学的形状（rectangle、circle、ellipse、polygon）と自動トリガー動作を備えた create_region、delete_region、list_regions。

  • 壁とドア: 標準、ドア（開/閉/施錠）、秘密のドア、窓、幽体の壁、カスタム座標（create_wall、list_walls、set_door_state）。

  • アンビエントライト: 座標またはグリッドセル配置、減光/明光半径、アニメーション効果、色の閾値（create_light、update_light、delete_light、list_lights）。

  • アンビエントサウンド: オーディオトラック、半径、音量、リピートモード（create_sound、delete_sound、list_sounds）。

  • 計測テンプレート: 円錐、円、光線、矩形の呪文効果範囲マーカー。方向回転と色に対応（create_template、delete_template、list_templates）。

  • 描画: フリーハンドおよび幾何学的形状、線/塗りつぶしスタイル、テキスト注釈（create_drawing、delete_drawing、list_drawings）。

  • マップノートとピン: ジャーナルエントリにリンクされたランドマークマーカー、またはスタンドアロンのラベル（create_note、delete_note、list_notes）。

  • タイルとプロップ: 装飾タイルと背景の配置（create_tile、delete_tile、list_tiles）。

  • キャンバスビューポートキャプチャ: 座標グリッドオーバーレイ（[col,row]）を焼き込んだ GM キャンバスビューポートのスクリーンショット（capture_scene）。

  • ターゲティングとアニメーションピング: アニメーションカメラピング（ping_canvas）でプレイヤーの注意を誘導し、トークンのターゲット照準を表示/設定（set_target、get_targets）。

• 🧙 トークンとアクター制御:

  • A* 経路探索移動: トークンが壁を迂回し、経路上の閉じたドアを自動的に開きながら移動します（move_token_pathfind）。

  • トークンの視覚と照明: 視界範囲、視覚モード、減光/明光の放射光、視覚検出角度を設定（update_token_vision）。

  • 汎用 ActiveEffects: 属性変更（key、mode、value、priority）と持続時間（rounds、seconds、turns）を備えたメカニカルなバフ/デバフの作成、更新、削除、検査。トップレベルまたは合成された非リンクトークンアクターに対して実行可能（create_actor_effect、update_actor_effect、delete_actor_effect、list_actor_effects）。

  • 状態異常: システム非依存の状態異常の適用/解除（apply_status_effect）。

  • コンペンディウムのアクターとアイテムのインポート: アイテムごとの自動エラーリカバリ付きで、コンペンディウムパックから NPC/モンスター文書全体をインポート（import_compendium_actor）、または特定のアイテムをアクターのインベントリにインポート（create_actor_item）。

  • システム属性の変更: JSON マージパッチを使用してアクターのシステムデータ（HP、一時 HP、通貨、リソース、呪文スロット）をパッチ適用（update_actor_attributes）。

• ⚔️ 戦闘エンカウンター管理: エンカウンターの作成、トークンからの戦闘参加者の投入、イニシアチブ順の管理、ターン/ラウンドの進行、アクティブな戦闘参加者の追跡、ゲームクロックの一時停止/再開（set_pause）、エンカウンターの終了。

• 📜 ワールド文書と整理:

  • フォルダー: アクター、アイテム、ジャーナル、シーンの階層フォルダー構造を管理（create_folder、list_folders）。

  • マクロ: スクリプト/チャットマクロの検査、作成、削除（create_macro、list_macros、delete_macro）。

  • プレイリストとオーディオ: マルチトラックプレイリストの作成、再生制御（再生、一時停止、停止）、トラック状態の調整（create_playlist、set_playlist_state、list_playlists）。

  • ロールテーブル: 自動連番範囲配分（1dN）付きテーブルの作成と、ライブ結果の抽選（create_roll_table、roll_table、list_roll_tables）。

  • 文書の所有権とユーザーロール: 文書単位の詳細な権限設定（set_document_ownership）と、自己降格ロックアウトガード付きのユーザーロール設定（set_user_role）。

  • ワールド設定: コアエンジン破損に対する組み込み保護付きで、モジュールおよびシステム設定を安全に検査・更新（get_world_setting、set_world_setting）。

  • アセットアップロード: ネイティブの FilePicker またはローカルファイルシステムを介して、画像、トークン、オーディオを Foundry の Data/ ストレージに直接アップロード（upload_asset）。

• 🌫️ シーン、天候、探索管理: アクティブシーンの切り替え、暗闇レベルの調整、全体照明の切り替え、環境天候効果の設定（set_scene_weather）、戦争の霧の探索リセット（reset_fog）。

• 🔍 ルールとコンペンディウム検索: コンテキスト付きスニペットでワールド文書、コンペンディウムパック、ルールテキストを検索（search_compendium_content、lookup_rule）。

Related MCP server: Foundry VTT MCP Bridge

🏗️ アーキテクチャ

このサーバーは、リアルタイム応答性と深いゲームエンジン統合を実現するハイブリッドアーキテクチャを採用しています。

┌─────────────────────────────────────────────────────────────┐
│                    AI Assistant / MCP Client                │
│             (Claude Desktop, Oh My Pi, VS Code)             │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP (stdio)
┌──────────────────────────────▼──────────────────────────────┐
│                    FoundryVTT MCP Server                    │
├──────────────────────────────┬──────────────────────────────┤
│  In-Memory World Cache       │  A* Pathfinding Router       │
│  (Live Socket.IO Sync)       │  Dice Notation Engine        │
└──────────────┬───────────────┴──────────────┬───────────────┘
               │ Socket.IO (Port 30000)       │ WebSocket (Port 31415)
               │ (modifyDocument / Events)    │ (Bridge Protocol)
┌──────────────▼──────────────────────────────▼───────────────┐
│                    FoundryVTT Game Engine                   │
│  ┌────────────────────────┐    ┌─────────────────────────┐  │
│  │   Active World & Data  │    │  Companion Module       │  │
│  │   (Actors, Scenes, …)  │    │  (foundryvtt-mcp-bridge)│  │
│  └────────────────────────┘    └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

1. Socket.IO プライマリ接続: 認証済みユーザー（mcp-api）として FoundryVTT に接続します。ワールド状態を自動的に同期・キャッシュし、modifyDocument プロトコルによる即時ルックアップと高頻度の文書変更を可能にします。

2. コンパニオンモジュールブリッジ（foundryvtt-mcp-bridge）: ブラウザ内で動作する軽量 Foundry モジュールで、キャンバス依存の操作（グリッドオーバーレイ付き PIXI キャンバススクリーンショット、ネイティブ Roll チャットカードレンダリング、文書スキーマのイントロスペクション、コンペンディウムアイテム抽出）を実行します。

3. オプションの REST API モジュール: ローカル REST モジュールがインストールされている場合、サーバーの診断、ログ取得、ヘルスレポートを提供します。

🚀 クイックスタート

1. 前提条件

• Node.js 18+ または Bun

• アクティブなワールドが実行されている FoundryVTT v11+ / v12+

• ゲームマスター または アシスタント GM ロールを持つ専用の Foundry ユーザーアカウント

2. 専用 Foundry ユーザーの設定

FoundryVTT で:

1. 設定 → ユーザー管理 を開く

2. ユーザー作成 をクリック

3. ユーザー名: mcp-api、パスワード: mcp（または任意）を設定

4. ロール: ゲームマスター（または書き込み権限が有効な アシスタント GM）

3. コンパニオンモジュールのインストール（推奨）

このリポジトリの foundry-module フォルダーを FoundryVTT の Data/modules/ ディレクトリにコピーします:

# Windows
cp -r foundry-module "%LOCALAPPDATA%/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

# macOS
cp -r foundry-module "~/Library/Application Support/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

# Linux
cp -r foundry-module "~/.local/share/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

FoundryVTT で モジュール管理 に移動し、FoundryVTT MCP Bridge を有効にします。

⚙️ 設定とクライアントセットアップ

環境変数

Claude Desktop の設定

claude_desktop_config.json に追加:

{
  "mcpServers": {
    "foundryvtt": {
      "command": "node",
      "args": ["<PATH_TO_REPO>/dist/index.js"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "mcp-api",
        "FOUNDRY_PASSWORD": "mcp",
        "FOUNDRY_WRITE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_PORT": "31415"
      }
    }
  }
}

Oh My Pi の設定

~/.omp/agent/mcp.json（または ~/.omp/mcp.json）に追加:

{
  "mcpServers": {
    "foundryvtt": {
      "type": "stdio",
      "command": "node",
      "args": ["<PATH_TO_REPO>/dist/index.js"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "mcp-api",
        "FOUNDRY_PASSWORD": "mcp",
        "FOUNDRY_WRITE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_PORT": "31415"
      },
      "timeout": 60000
    }
  }
}

🛠️ ツールカタログ（111 ツール）

1. リアルタイムイベント認識

• watch_events — カーソル指定のアクティビティログ（cursor、waitMs、limit、kinds、types、actions、sceneId、excludeSelf）をロングポーリングし、ポーリングなしで文書ブロードキャストとキャンバスアクティビティを取得します。

2. キャンバスと空間配置物

• create_region / delete_region / list_regions — 幾何学的形状（rectangle、circle、ellipse、polygon）と自動動作を備えたシーンリージョン（v12+）を管理。

• create_wall / delete_wall / list_walls / set_door_state — 壁とドアの完全なジオメトリ管理。

• create_light / update_light / delete_light / list_lights — アンビエント照明の制御（半径、色、アニメーション）。

• create_sound / delete_sound / list_sounds — キャンバスシーンへのアンビエントオーディオの配置。

• create_template / delete_template / list_templates — 呪文と効果の効果範囲テンプレート。

• create_drawing / delete_drawing / list_drawings — マップの形状、ゾーン、テキスト注釈。

• create_note / delete_note / list_notes — マップピンとランドマークマーカー。

• create_tile / delete_tile / list_tiles — 装飾タイルとマッププロップ。

• capture_scene — グリッド座標オーバーレイを焼き込んだアクティブシーンキャンバスのスクリーンショット。

• ping_canvas — 指定したピクセル座標にアニメーションキャンバスピングを発信。

• find_open_cells — トークン/プロップ配置に適したブロックされていないグリッドセルをシーンからスキャン。

• list_scene_assets — 解析されたタグと寸法付きで、マップ背景、トークンアート、オーディオファイルを検出。

• upload_asset — FilePicker またはローカルファイルシステムを介して、画像/オーディオファイルを Foundry の Data/ ディレクトリにアップロード。

3. トークンと移動

• spawn_token — カスタムサイズ、高度、座標でアクタートークンをシーンに配置します。

• delete_token — 基となるアクターを削除せずにシーンからトークンを削除します。

• list_tokens — アクティブなシーンまたは特定のシーンに配置されたトークンを一覧表示します。

• move_token — トークンを正確なピクセル座標にテレポートします。

• move_token_pathfind — 壁を回避し、ドアを自動的に開きながらA*経路探索を使用してトークンを移動します。

• move_tokens — 複数のトークンを同時に一括移動します。

• set_target / get_targets — 接続されたユーザー間でトークンのターゲット照準レチクルを設定・確認します。

• update_token_vision — 視界範囲、視界モード、明暗の放出光、角度を設定します。

• apply_status_effect — 簡単な状態異常（prone、stunned、blinded、invisible など）を切り替えます。

4. アクターとインベントリ

• create_world_actor / create_full_actor / delete_world_actor — アクタードキュメントを作成・削除します。

• import_compendium_actor — アイテムが埋め込まれたNPC/モンスターをコンペンディウムパックからインポートし、自動エラー回復を行います。

• search_actors — カーソルページネーション対応で、名前とタイプでアクターを検索します。

• get_actor_details — アクターのシステムデータ、統計、属性、体力を取得します。

• update_actor_attributes — ドットパス（attributes.hp.value、currency.gp）を使用してネストされたシステムデータをパッチします。

• get_actor_inventory — 完全なシステムプロパティを持つ所有アイテムを一覧表示します。

• create_actor_item — インラインアイテムを作成するか、コンペンディウムパックから直接インポートします（source: { type: 'compendium', compendiumId, itemId }）。

• update_actor_item — 所有アイテムにJSONマージパッチを適用します。

• delete_actor_item — アクターのインベントリから特定のアイテムを削除します。

• create_actor_effect / update_actor_effect / delete_actor_effect / list_actor_effects — メカニカルな変更（key、mode、value、priority）と持続時間を持つ汎用ActiveEffectsを、トップレベルまたは合成された非リンクトークンアクターに適用します。

5. 戦闘エンカウンター

• start_combat — エンカウンターを作成し、シーントークンから戦闘参加者をシードします。

• get_combat_state — 戦闘参加者のターン順、HP、AC、ラウンド数を取得します。

• set_initiative — 戦闘参加者のイニシアチブ値を設定し、ターンを並べ替えます。

• next_turn — ターントラッカーを進めます（ラウンド増分を処理し、敗北した戦闘参加者をスキップします）。

• set_pause — ゲームクロックを一時停止または再開します。

• end_combat — アクティブなエンカウンターを終了します。

6. ワールドドキュメントと整理

• list_folders / create_folder — アクター、アイテム、ジャーナル、シーンをネストされたフォルダに整理します。

• list_macros / create_macro / delete_macro — スクリプトおよびチャットマクロドキュメントを管理します。

• list_playlists / create_playlist / set_playlist_state / delete_playlist — オーディオプレイリストとサウンドコントロール。

• create_roll_table / delete_roll_table / roll_table / list_roll_tables — テーブル作成と結果ロール。

• get_world_setting / set_world_setting — コア保護付きでシステム/モジュール設定を確認・変更します。

• set_document_ownership — 詳細なドキュメント権限（none、limited、observer、owner）を設定します。

• get_users / set_user_role — 接続されたユーザーを一覧表示し、自己降格ロックアウトガード付きで権限ロールを変更します。

• create_journal_entry / get_journal / search_journals / delete_journal_entry — セッションノートとロアを管理します。

7. シーン、天候、探索

• create_scene / delete_scene / get_scene_info / switch_scene — シーン作成とプレイヤーアクティベーション。

• set_scene_weather — 天候効果（rain、snow、fog、""）を設定または解除します。

• set_scene_lighting — 周囲の暗さレベルとグローバル照明設定。

• reset_fog — アクティブなシーンで戦争の霧の探索をリセットします。

8. ゲームメカニクスとブリッジツール

• roll_dice — ローカルな数学的ダイス式の評価。

• roll_and_post — Foundryのネイティブエンジンで式を評価し、インタラクティブなチャットカードを投稿します。

• lookup_rule — ワールドジャーナルとシステムコンペンディウムパックからスニペットプレビュー付きでルールを検索します。

• get_document_schema — アクターとアイテムタイプのゲームシステムDataModelスキーマを調査します。

• search_compendium_content — コンペンディウムパックドキュメントとジャーナルページ内を深く検索します。

• send_chat_message / get_chat_messages — Foundryチャットログへのメッセージ投稿と読み取り。

• generate_npc / generate_loot — 即時プロシージャルジェネレーター。

9. 診断とロギング

• get_health_status / get_system_health — 接続とサーバーヘルスメトリクス。

• get_recent_logs / search_logs — サーバーログとエラースタックトレースを確認します。

• diagnose_errors — 最近のエラーを分析し、優先順位付けされた解決提案に変換します。

• refresh_world_data — キャッシュされたワールド状態スナップショットの再取得を強制します。

🧪 開発とテスト

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run complete unit test suite (713 tests)
npm test

# Run linter and formatting checks
npm run lint

# Start server in development watch mode
npm run dev

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。