Сервер Model Context Protocol (MCP), который интегрируется с FoundryVTT, позволяя помощникам ИИ взаимодействовать с игровыми сессиями на настольных компьютерах с помощью естественного языка.

Особенности

Dice Rolling — стандартная RPG-нотация с любой формулой Запрос данных — поиск и проверка актеров, предметов, сцен, журналов Игровое состояние — отслеживание боевых действий, сообщения в чате, присутствие пользователей Поколение контента — NPC, таблицы добычи, поиск правил World Search — полнотекстовый поиск по всем игровым объектам Live Connection — Сокет. IO загружает полное состояние мира на соединение MCP Resources — foundry:// URI для прямого доступа к данным Диагностика — дополнительный мониторинг состояния сервера (требуется модуль REST API)

Быстрый старт

Предпосылки

Node.js 18+ (или Bun)

• FoundryVTT сервер работает с активным миром MCP-совместимый клиент ИИ (Claude Desktop, Claude Code, VS Code и др.)

###Рекомендовано: Создайте выделенного пользователя API

Рекомендуется создать отдельную учетную запись пользователя FoundryVTT для сервера MCP, а не использовать собственную учетную запись GM или плеера. Это обеспечивает лучшую безопасность и аудит.

** В FoundryVTT: ** 1.Перейти к Конфигурация Управление пользователем 2.

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