FoundryVTT MCP 服务器

一个全面、生产级的 Model Context Protocol (MCP) 服务器，用于 Foundry Virtual Tabletop (FoundryVTT)。

该服务器使 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）掷骰。通过配套桥接（roll_and_post）直接将交互式、可点击的聊天卡片掷出并发布到 Foundry 聊天日志中。

• 🗺️ 完整画布与空间控制：创建、检查、更新和移除所有画布可放置物类型：

  • 场景区域（v12+）：create_region、delete_region、list_regions，支持几何形状（rectangle、circle、ellipse、polygon）和自动化触发行为。

  • 墙壁与门：标准、门（打开/关闭/锁定）、暗门、窗户、灵体墙壁和自定义坐标（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）。

  • 画布视口捕获：通过 capture_scene 截取 GM 画布视口，并带有烧录的坐标网格叠加（[col,row]）。

  • 目标与动画 Ping：通过动画相机 ping（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+ 运行活动世界

• 一个专用的 Foundry 用户账户，具有 Gamemaster 或 Assistant GM 角色

2. 配置专用 Foundry 用户

在 FoundryVTT 中：

1. 打开 配置 → 用户管理

2. 点击 创建用户

3. 设置用户名：mcp-api，密码：mcp（或您选择的密码）

4. 角色：Gamemaster（或启用写权限的 Assistant 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 — 管理场景区域（v12+），带几何形状（rectangle、circle、ellipse、polygon）和自动化行为。

• 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 — 在特定像素坐标处发出动画画布 ping。

• find_open_cells — 扫描场景以查找适合令牌/道具放置的未阻塞网格单元。

• list_scene_assets — 发现地图背景、令牌艺术和音频文件，带解析的标签和尺寸。

• upload_asset — 通过 FilePicker 或本地文件系统将图像/音频文件上传到 Foundry 的 Data/ 目录。

3. 令牌与移动

• spawn_token — 在场景中放置 Actor Token，可自定义尺寸、高度和坐标。

• delete_token — 从场景中移除 Token，而不会删除对应的 Actor。

• list_tokens — 列出当前活动场景或指定场景中已放置的 Token。

• move_token — 将 Token 传送到精确的像素坐标。

• move_token_pathfind — 使用 A* 路径规划移动 Token，可绕开墙壁障碍并自动开门。

• move_tokens — 批量同时移动多个 Token。

• set_target / get_targets — 设置并查看跨已连接用户的 Token 瞄准准星。

• update_token_vision — 配置视野范围、视野模式、暗/亮发光光源及角度。

• apply_status_effect — 切换简单状态效果（prone、stunned、blinded、invisible 等）。

4. 角色与物品栏

• create_world_actor / create_full_actor / delete_world_actor — 创建和删除 Actor 文档。

• import_compendium_actor — 从 compendium 包中导入完整 NPC/怪物，包含内嵌物品并支持自动错误恢复。

• search_actors — 按名称和类型查询 Actor，支持游标分页。

• get_actor_details — 获取 Actor 的系统数据、统计信息、属性和生命值。

• update_actor_attributes — 使用点路径（attributes.hp.value、currency.gp）修补嵌套的系统数据。

• get_actor_inventory — 列出 Actor 拥有的物品及其完整系统属性。

• create_actor_item — 创建内联物品，或直接从 compendium 包导入（source: { type: 'compendium', compendiumId, itemId }）。

• update_actor_item — 对拥有的物品应用 JSON 合并补丁。

• delete_actor_item — 从 Actor 的物品栏中删除指定物品。

• create_actor_effect / update_actor_effect / delete_actor_effect / list_actor_effects — 通用 ActiveEffects，支持机制性修改（key、mode、value、priority）和持续时间，可应用于顶层或合成的未链接 Token Actor。

5. 战斗遭遇

• start_combat — 创建遭遇，并从场景 Token 生成战斗参与者。

• get_combat_state — 获取战斗参与者的回合顺序、HP、AC 和回合数。

• set_initiative — 设置战斗参与者的先攻值并重新排列回合顺序。

• next_turn — 推进回合追踪器（处理回合递增并跳过已战败的战斗参与者）。

• set_pause — 暂停或恢复游戏时钟。

• end_combat — 终止当前进行的遭遇。

6. 世界文档与组织

• list_folders / create_folder — 在嵌套文件夹中组织 Actor、物品、日志和场景。

• 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 — 在世界日志和系统 compendium 包中搜索规则，并显示摘要预览。

• get_document_schema — 检查游戏系统 DataModel 架构，获取 Actor 和物品类型的定义。

• search_compendium_content — 深入搜索 compendium 包文档和日志页面中的内容。

• 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 License 授权。