一款与FoundryVTT集成的模型上下文协议（MCP）服务器，使AI助手能够通过自然语言与您的桌面游戏会话交互。

特色

• 掷骰子 — 标准RPG记谱法，任意公式
• 数据查询 — 搜索和检查演员、物品、场景、日志
• 游戏状态 — 战斗追踪、聊天消息、用户在场
• 内容生成 — NPC、战利品表、规则查询
• 世界搜索 — 涵盖所有游戏实体的全文搜索
• 实时连接 — Socket.IO 在连接上加载完整的世界状态
• MCP 资源 — foundry:// 直接访问数据的 URI
• 诊断 — 可选服务器健康监测（需要REST API模块）

快速启动

先决条件

• Node.js 18+（或称Bun）
• 运行活跃世界的FoundryVTT服务器
• 兼容MCP的AI客户端（Claude Desktop、Claude Code、VS Code等）

推荐：创建一个专用的 API 用户

建议为MCP服务器创建一个独立的FoundryVTT用户账户，而不是使用您自己的GM或玩家账户。这能提供更好的安全性和可审计性。

在FoundryVTT中：

1. 前往配置 → 用户管理

FoundryVTT MCP Server

A Model Context Protocol (MCP) server that integrates with FoundryVTT, allowing AI assistants to interact with your tabletop gaming sessions through natural language.

Features

• Dice Rolling — standard RPG notation with any formula
• Data Querying — search and inspect actors, items, scenes, journals
• Game State — combat tracking, chat messages, user presence
• Content Generation — NPCs, loot tables, rule lookups
• World Search — full-text search across all game entities
• Live Connection — Socket.IO loads complete world state on connect
• MCP Resources — foundry:// URIs for direct data access
• Diagnostics — optional server health monitoring (requires REST API module)

Quick Start

Prerequisites

• Node.js 18+ (or Bun)
• FoundryVTT server running with an active world
• MCP-compatible AI client (Claude Desktop, Claude Code, VS Code, etc.)

Recommended: Create a Dedicated API User

It is recommended to create a separate FoundryVTT user account for the MCP server rather than using your own GM or player account. This provides better security and auditability.

In FoundryVTT:

1. Go to Configuration → User Management
2. Click Create User
3. Set a username (e.g., mcp-api) and a strong password
4. Assign the Assistant GM role (needed to read world data and roll dice)
5. Use this account’s credentials in your MCP configuration

Benefits:

• Chat messages and actions from the MCP server are clearly attributed to a separate user
• You can revoke access by disabling the API user without affecting your own account
• Limits blast radius if credentials are ever exposed

Installation

Run directly without installing — no clone needed:

bunx foundryvtt-mcp

Or with npx:

npx -y foundryvtt-mcp

Client Configuration

Claude Desktop / Claude Code

Add to your MCP configuration (claude_desktop_config.json or .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

Add to your VS Code MCP settings:

{
  "servers": {
    "foundryvtt": {
      "command": "bunx",
      "args": ["foundryvtt-mcp"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "your_username",
        "FOUNDRY_PASSWORD": "your_password"
      }
    }
  }
}

Development Setup

For local development or contributing:

git clone https://github.com/laurigates/foundryvtt-mcp.git
cd foundryvtt-mcp
bun install