一个全面、生产级的 Model Context Protocol (MCP) 服务器，用于 Foundry Virtual Tabletop (FoundryVTT)。
该服务器使 AI 助手（Claude Desktop、Claude Code、Oh My Pi、VS Code、Cursor 等）能够作为 FoundryVTT 中完全有能力、自主的 共同 GM 和 GM 助手。它提供对游戏机制、角色、物品、令牌、战斗遭遇、画布可放置物（墙壁、灯光、声音、模板、绘图、笔记、瓦片）、播放列表、宏、掷骰表、宝典、世界设置和实时画布渲染的完整读写访问。
👁️ 实时事件流与活动日志（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)│ │
│ └────────────────────────┘ └─────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘Socket.IO 主连接：作为认证用户（mcp-api）连接到 FoundryVTT。自动同步和缓存世界状态，实现即时查找和通过 modifyDocument 协议进行高频文档修改。
配套模块桥接（foundryvtt-mcp-bridge）：一个在浏览器中运行的轻量级 Foundry 模块，执行画布绑定操作（带网格叠加的 PIXI 画布截图、原生 Roll 聊天卡片渲染、文档模式内省和宝典物品提取）。
可选 REST API 模块：当本地 REST 模块安装时，提供服务器诊断、日志检索和健康报告。
Node.js 18+ 或 Bun
FoundryVTT v11+ / v12+ 运行活动世界
一个专用的 Foundry 用户账户，具有 Gamemaster 或 Assistant GM 角色
在 FoundryVTT 中：
打开 配置 → 用户管理
点击 创建用户
设置用户名：mcp-api，密码：mcp（或您选择的密码）
角色：Gamemaster（或启用写权限的 Assistant GM）
将本仓库中的 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。
变量 | 必需 | 默认值 | 描述 |
| 是 |
| FoundryVTT 服务器 URL |
| 是 | — | FoundryVTT 用户账户名 |
| 是 | — | FoundryVTT 用户账户密码 |
| 否 |
| 启用游戏状态修改（墙壁、角色、令牌等） |
| 否 |
| 启用用于画布截图和聊天掷骰的 WebSocket 桥接 |
| 否 |
| 配套模块桥接的 WebSocket 端口 |
| 否 | — | Foundry |
| 否 | — | 用于服务器诊断工具的可选 REST API 密钥 |
| 否 |
| 内存事件日志环形缓冲区容量 |
| 否 |
|
|
| 否 |
| 日志详细程度（ |
添加到 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"
}
}
}
}添加到 ~/.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
}
}
}watch_events — 长轮询游标寻址的活动日志（cursor、waitMs、limit、kinds、types、actions、sceneId、excludeSelf），捕获文档广播和画布活动，无需轮询。
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/ 目录。
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 等）。
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。
start_combat — 创建遭遇，并从场景 Token 生成战斗参与者。
get_combat_state — 获取战斗参与者的回合顺序、HP、AC 和回合数。
set_initiative — 设置战斗参与者的先攻值并重新排列回合顺序。
next_turn — 推进回合追踪器（处理回合递增并跳过已战败的战斗参与者）。
set_pause — 暂停或恢复游戏时钟。
end_combat — 终止当前进行的遭遇。
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 — 管理会话笔记和世界设定资料。
create_scene / delete_scene / get_scene_info / switch_scene — 创建场景并切换玩家当前激活的场景。
set_scene_weather — 设置或清除天气效果（rain、snow、fog、""）。
set_scene_lighting — 环境黑暗程度和全局光照设置。
reset_fog — 重置当前活动场景的战争迷雾探索状态。
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 — 即时程序化生成器。
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 授权。
This server cannot be deployed
Connect any AI to your Foundry VTT world: actors, combat, dice, journals, tokens, compendiums.
D&D and TTRPG campaign manager for GMs: your AI reads and writes a live, typed campaign database.
Create AI Characters and generate their DM and comment replies from any MCP client.
Your tabletop campaign's journal, wiki, map, character sheets and combat tracker.
