Foundry VTT MCP Bridge

将 Foundry VTT 连接到 Claude Desktop，通过模型上下文协议 (MCP) 实现 AI 驱动的战役管理。目前支持《龙与地下城》第五版 (D&D 5e) 和《开拓者》第二版 (PF2E)。大多数 MCP 工具与系统无关，但角色创建和图鉴工具仅适用于 D&D 5e 和 PF2E。

概述

Foundry MCP Bridge 支持与您的 Foundry VTT 游戏数据进行自然的 AI 对话：

• 任务创建：根据提示创建任务，并结合您世界和日志中已有的内容

• 角色管理：查询角色属性、能力和信息

• 图鉴搜索：使用自然语言查找物品、法术和生物

• 内容创作：通过简单的提示生成角色、NPC 和任务日志

• 场景信息：访问当前场景数据和世界详情

• 掷骰协调：带有玩家目标的交互式掷骰请求

• 战役管理：多部分任务和战役追踪

• 地图生成：根据提示创建地图，并使用可选的 ComfyUI 组件自动上传到 Foundry VTT 场景中

本项目在 Claude Code 的协助下构建。如果您喜欢这个项目，请考虑 在 Patreon 上支持它。

Related MCP server: Coreflux MCP Server

安装

先决条件

• Foundry VTT v13

• 支持 MCP 的 Claude Desktop

• Windows（用于自动安装程序）或 Node.js 18+（用于手动安装）

选项 1：Windows 安装程序

Windows 安装程序视频指南

1. 从 Releases 下载最新的 FoundryMCPServer-Setup-vx.x.x.exe

2. 运行安装程序 - 它将：

   • 安装带有捆绑 Node.js 运行时的 MCP 服务器

   • 配置 Claude Desktop MCP 服务器设置

   • 可选地将 Foundry 模块和 ComfyUI 地图生成安装到您的 VTT 安装目录

   • 在安装过程中为您的 GPU 类型选择 Cuda 版本

3. 重启 Claude Desktop

4. 在您的 Foundry 模块管理中启用 "Foundry MCP Bridge"

选项 2：Mac 安装程序

1. 从 Releases 下载最新的 FoundryMCPServer-vx.x.x.dmg

2. 运行 dmg 内的软件包安装程序 - 它将：

   • 打开 DMG 并双击 PKG 安装程序

   • 配置 Claude Desktop MCP 服务器设置

   • 可选地将 Foundry 模块和 ComfyUI 地图生成安装到您的 Foundry VTT 安装目录

3. 重启 Claude Desktop

4. 在您的 Foundry 模块管理中启用 "Foundry MCP Bridge"

选项 3：手动安装

安装 Foundry 模块

1. 打开 Foundry VTT v13

2. 在 Foundry 插件菜单中选择安装模块

3. 在窗口底部，添加清单 URL：https://github.com/adambdooley/foundry-vtt-mcp/blob/master/packages/foundry-module/module.json 并点击安装

4. 在模块管理中启用 "Foundry MCP Bridge"

   • 请勿更改模块 ID 或文件夹名称。 MCP 后端和 Claude 集成都要求模块位于名为 foundry-mcp-bridge 的目录中。重命名 module.json 中的 ID 会破坏套接字路由，导致 Claude 无法识别后端。

安装 MCP 服务器

# Clone repository
git clone https://github.com/adambdooley/foundry-vtt-mcp.git
cd foundry-vtt-mcp

# Install dependencies and build
npm install
npm run build

配置 Claude Desktop

将此内容添加到您的 Claude Desktop 配置文件 (claude_desktop_config.json) 中：

{
  "mcpServers": {
    "foundry-mcp": {
      "command": "node",
      "args": ["path/to/foundry-vtt-mcp/packages/mcp-server/dist/index.js"],
      "env": {
        "FOUNDRY_HOST": "localhost",
        "FOUNDRY_PORT": "31415"
      }
    }
  }
}

启动 Claude Desktop 将启动 MCP 服务器。

入门指南

1. 启动 Foundry VTT 并加载您的世界

2. 打开 Claude Desktop

3. 与 Claude 聊天，讨论您当前加载的 Foundry 世界

使用示例

连接后，您可以询问 Claude Desktop：

• "显示我角色 Clark 的属性"

• "查找所有挑战等级 (CR) 为 12 的类人生物以进行遭遇战"

• "创建一个关于调查失踪村民的任务"

• "为 Tulkas 进行一次隐匿检定"

• "当前 Foundry 场景里有什么？"

• "在 Foundry 中为我创建一个河畔小屋的小地图"

功能

• 36 个 MCP 工具，允许 Claude 与 Foundry 交互

• 角色管理：访问属性、能力、物品栏和详细的实体信息

• 令牌操作：移动、更新、删除令牌并管理状态条件

• 增强的图鉴搜索：按 CR、类型、能力等进行即时过滤

• 内容创作：生成角色、NPC 和任务日志

• 战役管理：带有进度仪表板的多部分任务追踪

• 交互式掷骰系统：从 Claude 向玩家发送不同的掷骰请求

• 角色所有权：管理玩家对角色和令牌的权限

• 仅限 GM：MCP Bridge 仅连接到游戏管理员 (Game Master) 用户

• 地图生成：一个便携式 ComfyUI 后端，可根据提示生成战斗地图

• 远程连接：通过浏览器（已在 Google Chrome 上测试）启动到 MCP 服务器和 ComfyUI 的 WebRTC 连接

• Windows 和 Mac 安装程序：自动安装用于 Claude Desktop 的 Foundry MCP 服务器、Foundry VTT 模块以及带有依赖项的 ComfyUI 后端

MCP 工具

• 1 get-world-info

• 2 list-scenes

• 3 get-current-scene

• 4 get-available-conditions

• 5 list-compendium-packs

• 6 list-characters

• 7 get-character

• 8 search-character-items

• 9 get-character-entity

• 10 get-token-details

• 11 toggle-token-condition (add)

• 12 toggle-token-condition (remove)

• 13 update-token

• 14 search-compendium

• 15 get-compendium-item

• 16 get-compendium-entry-full

• 17 list-creatures-by-criteria

• 18 list-journals

• 19 create-quest-journal

• 20 update-quest-journal

• 21 search-journals

• 22 link-quest-to-npc

• 23 list-actor-ownership

• 24 assign-actor-ownership

• 25 remove-actor-ownership

• 26 move-token

• 27 use-item

• 28 request-player-rolls

• 29 generate-map

• 30 check-map-status

• 31 cancel-map-job

• 32 switch-scene

• 33 create-actor-from-compendium

• 34 list-dsa5-archetypes

• 35 create-dsa5-character-from-archetype

• 36 create-campaign-dashboard

设置

• 增强生物索引：配置“增强索引”按钮，进入“增强生物索引”子菜单（详情见下文）

• 地图生成服务配置：配置“地图生成”按钮，进入“地图生成服务”子菜单（详情见下文）

• 启用 MCP Bridge：默认应勾选，状态应显示为已连接。它可用于在游戏内关闭 MCP Bridge 连接，而无需禁用插件本身。

• 连接类型：可设置为“自动”以自动检测连接类型。也可以强制设置为用于互联网连接的 WebRTC 或用于本地连接的 Websocket。

• Websocket 服务器主机：Claude Desktop MCP 服务器位置的 IP 地址。仅用于本地网络 Websocket 连接。远程服务器使用 WebRTC。默认为 localhost。

• 允许写入操作：这将阻止 Claude 对世界内容进行任何更改，并将其限制为仅读取。

• 单次请求最大角色数：这是一个故障保护机制，用于防止单次请求创建大量角色。它不会限制多次请求创建的角色总数。

• 显示连接消息：可以关闭 Foundry MCP Bridge 的连接横幅消息。

• 断开后自动重连：如果连接丢失，将自动尝试重新连接。

• 连接检查频率：检查连接状态的频率。

增强生物索引子菜单

• 重建生物索引：如果出现问题或与图鉴中的更改不同步，此按钮将重建生物索引。

• 启用增强生物索引：应保持开启，因为 Claude 会在世界文件中构建额外的元数据，以提供更好的搜索效果。

• 包更改时自动重建索引：尚未完全测试的实验性功能。

地图生成服务子菜单

• 服务状态：有三个按钮：检查状态、启动服务和停止服务。这些按钮有助于监控和控制从 Foundry MCP Bridge 到由 Claude Desktop 应用程序启动的 ComfyUI 后端的连接。

• 自动启动地图生成服务：控制在 Foundry 世界启动时是否自动连接 ComfyUI 服务。

• 生成质量：控制 ComfyUI 中 SDXL 检查点生成的地图质量。“低”使用 8 步生成，“中”使用 20 步生成，“高”使用 35 步。此图像生成中使用的 D&D Battlemaps SDXL Upscale v1.0 检查点建议使用 35 步，但在低端 GPU 或没有 CUDA 的 GPU 上，此生成过程将需要几分钟。这些选项可以在质量和生成速度之间进行权衡。

架构

Claude Desktop ↔ MCP Protocol ↔ MCP Server ↔ WebSocket ↔ Foundry Module ↔ Foundry VTT
                                     ↓
                              ComfyUI Service
                              (AI Map Generation)

• Foundry 模块：在 Foundry VTT 内提供安全的数据访问

• MCP 服务器：处理 Claude Desktop 通信的外部 Node.js 服务器

• 地图生成服务：由 Claude Desktop 启动的无头 ComfyUI 后端

• 无需 API 密钥：使用您现有的 Claude Desktop 订阅

安全与权限

• 仅限 GM 访问：所有功能仅限于游戏管理员用户

• 可配置权限：控制 Claude 可以访问和修改的数据

• 基于会话的身份验证：使用 Foundry 内置的身份验证系统

系统要求

• Foundry VTT：版本 13

• Claude Desktop：支持 MCP 的最新版本

• Claude Pro/Max 计划：连接到 MCP 服务器所必需

• 操作系统：Windows 10/11（安装程序），或其他操作系统/带有 Node.js 18+ 的手动 Windows 安装

• GPU 要求：至少 8GB 显存的 GPU

模式冒烟测试

MCP 模式冒烟测试验证工具模式是否正确加载，并且不会强制执行过于严格的 additionalProperties 默认值。

npm -w @foundry-mcp/server run build
npm run test:mcp:schema

支持与开发

• 问题：在 GitHub Issues 上报告错误

• YouTube 频道：订阅以获取更新和教程

• 文档：使用 TypeScript 构建，包含全面的文档

• 许可证：MIT 许可证（安装程序的捆绑组件包含额外的第三方许可证）