FoundryVTT MCP服务器
](https://www.npmjs.com/package/foundryvtt-mcp) 
A. 模型上下文协议 （MCP）服务器与FoundryVTT集成，允许AI助手通过自然语言与您的桌面游戏会话进行交互。
特性
- 掷骰子 --任何公式的标准RPG符号
- 数据查询 --搜索和检查演员、物品、场景、日记
- 游戏状态 --战斗跟踪、聊天消息、用户状态
- 内容生成 --NPC、战利品表、规则查找
- 世界搜索 --所有游戏实体的全文搜索
- 实时连接 --插座。IO在连接上加载完整的世界状态
- MCP资源 —
foundry://用于直接数据访问的URI - 诊断 -可选的服务器运行状况监视（需要REST API模块）
快速开始
先决条件
- Node.js 18+（或 包子)
- FoundryVTT服务器在活跃世界中运行
- MCP兼容的AI客户端（克劳德桌面、克劳德代码、VS代码等）
建议：创建一个专门的API用户
建议为MCP服务器创建一个单独的FoundryVTT用户帐户，而不是使用您自己的GM或玩家帐户。这提供了更好的安全性和可审计性。
在FoundryVTT：
- 首选 配置 → 用户管理
- 点击 创建用户
- 设置用户名（例如。，
mcp-api)以及一个强密码 - 分配 总经理助理 角色（需要读取世界数据和掷骰子）
- 在MCP配置中使用此帐户的凭据
优点：
- 来自MCP服务器的聊天消息和操作显然归属于单独的用户
- 您可以通过禁用API用户来撤销访问权限，而不会影响您自己的帐户
- 如果证书被暴露，则限制爆炸半径
安装
直接运行，无需安装——无需克隆：
bunx foundryvtt-mcp或者使用npx：
npx -y foundryvtt-mcp客户端配置
克劳德桌面/克劳德代码
添加到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 配置。
要手动配置，请参阅 配置指南.
环境变量
| 变量 | 必填 | 描述 |
|---|---|---|
FOUNDRY_URL | 是 | FoundryVTT服务器URL（例如。， http://localhost:30000) |
FOUNDRY_USERNAME | 是 | FoundryVTT用户帐户 |
FOUNDRY_PASSWORD | 是 | FoundryVTT用户密码 |
FOUNDRY_USER_ID | 否 | 绕过用户名到ID解析 |
FOUNDRY_API_KEY | 无 | REST API模块密钥（启用诊断工具） |
LOG_LEVEL | 没有 | debug, info, warn，或 error （默认值： info) |
FOUNDRY_TIMEOUT | 否 | 请求超时（毫秒）（默认值： 10000) |
用法
问你的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--最近的聊天记录
世界
search_world--所有游戏实体的全文搜索get_world_summary--当前世界状况概述refresh_world_data--从FoundryVTT重新加载世界数据
游戏机制
roll_dice--用任何公式掷骰子lookup_rule--游戏规则和咒语描述
内容生成
generate_npc--创建随机NPCgenerate_loot--创造适合等级的宝藏
诊断（需要REST API模块）
get_recent_logs--检索筛选的FoundryVTT日志search_logs--使用正则表达式模式搜索日志get_system_health--服务器性能和健康指标diagnose_errors--分析错误并提出故障排除建议get_health_status--综合健康诊断
可用资源
foundry://actors--世界上所有的演员foundry://items--世界上所有的物品foundry://scenes--所有场景foundry://scenes/current--当前活动场景foundry://journals--所有日记账分录foundry://users--在线用户foundry://combat--主动作战状态foundry://world/settings--世界和活动设置foundry://system/diagnostics-系统诊断（需要REST API模块）
故障排除
连接和设置帮助程序在源代码树中提供（不是已发布的 bin)，所以从dev checkout运行它们：
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详细指南： 故障排除.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)看 开发指南 用于项目结构、添加工具、测试和构建。
路线图
看 功能跟踪器 已完成和计划中的功能。
贡献
看 贡献.md.
许可证
MIT许可证——见 许可证 了解详情。
支持
- 问题:
- Discord 的中文翻译是“不和谐”或“纷争”。: FoundryVTT不一致 #api开发
- 文档: FoundryVTT API
致谢
- 为优秀的VTT平台创建VTT团队
- 模型上下文协议的拟人化
- 桌面游戏社区提供灵感和反馈