FoundryVTT MCP Server

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

Возможности

• Бросок кубиков — стандартная RPG-нотация с любой формулой

• Запросы данных — поиск и просмотр актёров, предметов, сцен, журналов

• Состояние игры — отслеживание боя, сообщения чата, присутствие пользователей

• Генерация контента — NPC, таблицы добычи, поиск правил

• Поиск по миру — полнотекстовый поиск по всем игровым сущностям

• Живое подключение — Socket.IO загружает полное состояние мира при подключении

• MCP-ресурсы — URI foundry:// для прямого доступа к данным

• Диагностика — необязательный мониторинг состояния сервера (требуется модуль REST API)

Related MCP server: FoundryVTT MCP Server

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

Предварительные требования

• Node.js 18+ (или Bun)

• Запущенный сервер FoundryVTT с активным миром

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

Рекомендуется: создайте отдельного API-пользователя

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

В FoundryVTT:

1. Перейдите в Configuration → User Management

2. Нажмите Create User

3. Укажите имя пользователя (например, mcp-api) и надёжный пароль

4. Назначьте роль Assistant 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

Добавьте в настройки MCP вашего VS Code:

{
  "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.

Для ручной настройки см. Руководство по конфигурации.

Переменные окружения

Использование

Спросите вашего ИИ-ассистента, например:

• «Брось 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 актёра (HP, валюта, ячейки заклинаний и т.д.)

• 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, *) вместо её игнорирования. Скобки — единственное различие в транспорте: FoundryVTT вычисляет их, когда установлен FOUNDRY_API_KEY, локальный роллер отклоняет их в противном случае

• 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), поэтому запускайте их из dev-копии:

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

• Сообщество настольных игр за вдохновение и обратную связь