FoundryVTT MCP

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：

1. 首选 配置 → 用户管理
2. 点击 创建用户
3. 设置用户名（例如。， mcp-api)以及一个强密码
4. 分配 总经理助理 角色（需要读取世界数据和掷骰子）
5. 在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 配置。

要手动配置，请参阅 配置指南.

环境变量

用法

问你的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 --创建随机NPC
• generate_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团队
• 模型上下文协议的拟人化
• 桌面游戏社区提供灵感和反馈