FoundryVTT MCP Server

一个集成了 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 服务器创建一个单独的 FoundryVTT 用户账户，而不是使用你自己的 GM 或玩家账户。这样可以提供更好的安全性和可审计性。

在 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 — 开始新的遭遇，从令牌中填充战斗者（不检查现有战斗 — 在活跃战斗中调用它会创建第二个遭遇）

• next_turn — 将当前战斗推进到下一回合（循环到下一轮）

• end_combat — 结束（删除）当前战斗遭遇

• set_initiative — 在当前战斗中设置战斗者的先攻值，如果重新排序导致行动者移动，则同时移动回合标记

• move_token — 将令牌移动到其场景上的新 x/y 坐标

• apply_status_effect — 在令牌的角色上应用或移除状态效果（例如倒地、眩晕）

• update_actor_attributes — 修补角色的 system 属性（生命值、货币、法术位等）

• create_actor_item — 向角色添加内联物品

• update_actor_item — 对角色的物品应用 JSON 合并补丁

• delete_actor_item — 从角色中移除物品

• create_journal_entry — 创建包含一个或多个文本页面的日志条目（默认仅 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)

有关项目结构、添加工具、测试和构建，请参阅 开发指南。

路线图

有关已完成和计划的功能，请参阅 功能跟踪器。

贡献

请参阅 CONTRIBUTING.md。

许可证

MIT 许可证 — 详情请参阅 LICENSE。

支持

• 问题：GitHub Issues

• Discord：FoundryVTT Discord #api-development

• 文档：FoundryVTT API

致谢

• FoundryVTT 团队，感谢他们出色的 VTT 平台

• Anthropic 提供的 Model Context Protocol

• 桌面角色扮演游戏社区提供的灵感和反馈