FoundryVTT MCP サーバー

FoundryVTT と統合する Model Context Protocol (MCP) サーバーです。AI アシスタントが自然言語を通じてテーブルトークゲームのセッションと対話できるようにします。

機能

• ダイスロール — 任意の数式に対応した標準 RPG 記法

• データ照会 — アクター、アイテム、シーン、ジャーナルの検索と閲覧

• ゲーム状態 — 戦闘追跡、チャットメッセージ、ユーザーの在席状況

• コンテンツ生成 — NPC、戦利品テーブル、ルール参照

• ワールド検索 — すべてのゲームエンティティにわたる全文検索

• ライブ接続 — Socket.IO が接続時に完全なワールド状態を読み込み

• MCP リソース — データへの直接アクセスを提供する foundry:// URI

• 診断 — オプションのサーバーヘルスモニタリング（REST API モジュールが必要）

Related MCP server: FoundryVTT MCP Server

クイックスタート

前提条件

• Node.js 18+（または Bun）

• アクティブなワールドで稼働中の FoundryVTT サーバー

• MCP 対応 AI クライアント（Claude Desktop、Claude Code、VS Code など）

推奨: 専用 API ユーザーの作成

MCP サーバーには、自身の GM アカウントやプレイヤーアカウントではなく、専用の FoundryVTT ユーザーアカウントを作成することをお勧めします。これにより、セキュリティと監査性が向上します。

FoundryVTT 内での操作:

1. 設定 → ユーザー管理 に移動

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

3. ユーザー名（例: mcp-api）と強力なパスワードを設定

4. アシスタント GM ロールを割り当て（ワールドデータの読み取りとダイスロールに必要）

5. このアカウントの認証情報を MCP 設定で使用

利点:

• MCP サーバーからのチャットメッセージと操作が別ユーザーとして明確に記録される

• API ユーザーを無効化することでアクセスを失効させられ、自身のアカウントには影響しない

• 認証情報が漏洩した場合の被害範囲を限定できる

インストール

インストールせずに直接実行 — クローンは不要です:

bunx foundryvtt-mcp

または npx を使用:

npx -y foundryvtt-mcp

クライアント設定

Claude Desktop / Claude Code

MCP 設定（claude_desktop_config.json または .mcp.json）に追加:

{
  "mcpServers": {
    "foundryvtt": {
      "command": "bunx",
      "args": ["foundryvtt-mcp"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "your_username",
        "FOUNDRY_PASSWORD": "your_password"
      }
    }
  }
}

VS Code

VS Code の MCP 設定に追加:

{
  "servers": {
    "foundryvtt": {
      "command": "bunx",
      "args": ["foundryvtt-mcp"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "your_username",
        "FOUNDRY_PASSWORD": "your_password"
      }
    }
  }
}

開発環境のセットアップ

ローカル開発やコントリビューション用:

git clone https://github.com/laurigates/foundryvtt-mcp.git
cd foundryvtt-mcp
bun install
bun run setup-wizard

セットアップウィザードが FoundryVTT サーバーを検出し、接続をテストして、.env 設定を生成します。

手動で設定する場合は、設定ガイド を参照してください。

環境変数

使用方法

AI アシスタントに次のようなことを依頼できます:

• 「攻撃ロールで 1d20+5 を振って」

• 「このシーンのすべての NPC を表示して」

• 「現在の戦闘のイニシアチブ順は？」

• 「ドラゴンに関連するものをワールド全体から検索して」

• 「ランダムな NPC 商人を生成して」

利用可能なツール

データアクセス

• search_actors — キャラクター、NPC、モンスターを検索

• get_actor_details — 詳細なキャラクター情報

• search_items — 装備、呪文、消耗品を検索

• get_scene_info — 現在のシーンの詳細

• search_journals — ノートとハンドアウトを検索

• get_journal — 特定のジャーナルエントリを取得

• get_users — ユーザー、ロール、オンライン状態の一覧

• get_combat_state — 戦闘状態とイニシアチブ順

• get_chat_messages — 最近のチャット履歴

書き込み操作（FOUNDRY_WRITE_ENABLED=true が必要）

ゲーム状態の変更はデフォルトで無効です。これらは認証済みセッションを介して Socket.IO の modifyDocument プロトコルを使用し、接続ユーザーには GM/オーナー権限が必要です。有効にするには FOUNDRY_WRITE_ENABLED=true を設定してください。

• start_combat — 新しい遭遇を開始し、トークンから戦闘参加者を投入（既存の戦闘をチェックしません — アクティブな戦闘中に呼び出すと2つ目の遭遇が作成されます）

• next_turn — アクティブな戦闘を次のターンに進める（次のラウンドに折り返します）

• end_combat — アクティブな戦闘遭遇を終了（削除）

• set_initiative — アクティブな戦闘で戦闘参加者のイニシアチブを設定し、並べ替えで順位が変わった場合は行動中の戦闘参加者とともにターンマーカーを移動

• move_token — トークンをそのシーン上の新しい x/y 座標に移動

• apply_status_effect — トークンのアクターに状態異常（例: 伏せ、朦朧）を適用または解除

• update_actor_attributes — アクターの system 属性（HP、通貨、呪文スロットなど）をパッチ適用

• create_actor_item — アクターにインラインアイテムを追加

• update_actor_item — アクターのアイテムに JSON マージパッチを適用

• delete_actor_item — アクターからアイテムを削除

• create_journal_entry — 1つ以上のテキストページを持つジャーナルエントリを作成（デフォルトでは GM のみ; visibility を渡すとプレイヤーも読めるようになります）

ワールド

• search_world — すべてのゲームエンティティにわたる全文検索

• get_world_summary — 現在のワールド状態の概要

• refresh_world_data — FoundryVTT からワールドデータを再読み込み。接続が切断された後に必要。切断中の更新はキャッシュに再生されないため

ゲームメカニクス

• roll_dice — ダイスロール。+/- で結合されたダイス項（NdS）と整数に対応し、未対応の記法（4d6kh3、1d20r1、*）は破棄せず拒否します。括弧が唯一の転送上の違いです: FOUNDRY_API_KEY が設定されている場合は FoundryVTT が評価し、設定されていない場合はローカルローラーが拒否します

• lookup_rule — スタブ: テンプレート化されたプレースホルダーを返し、ルールソースを参照しません

コンテンツ生成

• generate_npc — NPC テキストを生成（ワールドには書き込まれません）

• generate_loot — レベルに応じた宝物テキストを生成（ワールドには書き込まれません）

診断（REST API モジュールが必要）

• get_recent_logs — フィルタリングされた FoundryVTT ログを取得

• search_logs — パターンでログを検索し、一致するエントリを一覧表示

• get_system_health — バージョン、ユーザー/モジュール数、メモリ、ログエラー数を含むサーバーヘルスステータス（CPU やディスクのメトリクスはなし）

• diagnose_errors — スタブ: 固定の「エラーは検出されませんでした」というサマリーを返します

• get_health_status — 包括的なヘルス診断。キャッシュがライブ変更の追跡を停止した場合にワールドスナップショットにフラグを立てます

利用可能なリソース

• foundry://actors — ワールド内のすべてのアクター

• foundry://items — ワールド内のすべてのアイテム

• foundry://scenes — すべてのシーン

• foundry://scenes/current — 現在アクティブなシーン

• foundry://journals — すべてのジャーナルエントリ

• foundry://users — オンラインのユーザー

• foundry://combat — アクティブな戦闘状態。combatants はイニシアチブ順に並ぶため、combat.turn で直接インデックスを参照できます

• foundry://world/settings — ワールドとキャンペーンの設定

• foundry://system/diagnostics — システム診断（REST API モジュールが必要）

トラブルシューティング

接続性とセットアップのヘルパーはソースツリー内にあります（公開された bin には含まれません）。開発チェックアウトから実行してください:

git clone https://github.com/laurigates/foundryvtt-mcp.git
cd foundryvtt-mcp && bun install
bun run test-connection   # Probe FoundryVTT connectivity
bun run setup-wizard      # Re-run interactive setup

詳細ガイド: TROUBLESHOOTING.md

開発

bun run build          # Compile TypeScript and make dist/index.js executable
bun run dev            # Development mode with hot reload
bun test               # Unit tests (Vitest)
bun run test:e2e       # E2E tests (Playwright)
bun run lint           # Lint code (Biome)
bun run smoke          # Startup smoke test against the local build
bun run smoke:pack     # Pack-and-install smoke test (mirrors what npx consumers get)

プロジェクト構造、ツールの追加、テスト、ビルドについては 開発ガイド を参照してください。

ロードマップ

完了済みおよび計画中の機能については 機能トラッカー を参照してください。

コントリビューション

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

ライセンス

MIT ライセンス — 詳細は LICENSE を参照してください。

サポート

• 問題報告: GitHub Issues

• Discord: FoundryVTT Discord #api-development

• ドキュメント: FoundryVTT API

謝辞

• 優れた VTT プラットフォームを提供してくれた FoundryVTT チーム

• Model Context Protocol を提供してくれた Anthropic

• インスピレーションとフィードバックをくれたテーブルトークゲームコミュニティ