Foundry VTT MCP Bridge

Подключите Foundry VTT к Claude Desktop для управления кампанией с помощью ИИ через протокол Model Context Protocol (MCP). В настоящее время поддерживаются Dungeons and Dragons Fifth Edition и Pathfinder Second Edition. Большинство инструментов MCP являются универсальными, но инструменты для создания персонажей и поиска по компендиумам работают только с D&D5e и PF2E.

Обзор

Foundry MCP Bridge обеспечивает естественное общение с ИИ по данным вашей игры в Foundry VTT:

• Создание квестов: Создавайте квесты на основе подсказок, которые включают то, что уже существует в вашем мире и журналах

• Управление персонажами: Запрашивайте характеристики, способности и информацию о персонажах

• Поиск по компендиумам: Находите предметы, заклинания и существ, используя естественный язык

• Создание контента: Генерируйте актеров, NPC и журналы квестов из простых подсказок

• Информация о сцене: Получайте доступ к данным текущей сцены и деталям мира

• Координация бросков кубиков: Интерактивные запросы на броски с выбором целей среди игроков

• Управление кампанией: Отслеживание многоэтапных квестов и кампаний

• Генерация карт: Создавайте карты из подсказок и автоматически загружайте их в сцены в Foundry VTT с помощью дополнительного компонента ComfyUI

Этот проект был создан с помощью Claude Code. Если вам нравится этот проект, рассмотрите возможность поддержать его на Patreon.

Related MCP server: Coreflux MCP Server

Установка

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

• Foundry VTT v13

• Claude Desktop с поддержкой MCP

• Windows (для автоматического установщика) или Node.js 18+ для ручной установки

Вариант 1: Установщик для Windows

Видеоинструкция по установщику для Windows

1. Скачайте последний файл FoundryMCPServer-Setup-vx.x.x.exe из раздела Releases

2. Запустите установщик - он выполнит:

   • Установку MCP-сервера с включенной средой выполнения Node.js

   • Настройку параметров MCP-сервера в Claude Desktop

   • Опциональную установку модуля Foundry и генерации карт ComfyUI в вашу установку VTT

   • Выбор версии Cuda для вашего типа GPU во время установки

3. Перезапустите Claude Desktop

4. Включите "Foundry MCP Bridge" в управлении модулями Foundry

Вариант 2: Установщик для Mac

1. Скачайте последний файл FoundryMCPServer-vx.x.x.dmg из раздела Releases

2. Запустите установщик пакета внутри dmg - он выполнит:

   • Открытие DMG и двойной клик по установщику PKG

   • Настройку параметров MCP-сервера в Claude Desktop

   • Опциональную установку модуля Foundry и генерации карт ComfyUI в вашу установку Foundry VTT

3. Перезапустите Claude Desktop

4. Включите "Foundry MCP Bridge" в управлении модулями Foundry

Вариант 3: Ручная установка

Установка модуля Foundry

1. Откройте Foundry VTT v13

2. Выберите установку модуля в меню дополнений Foundry

3. В нижней части окна добавьте URL манифеста: https://github.com/adambdooley/foundry-vtt-mcp/blob/master/packages/foundry-module/module.json и нажмите установить

4. Включите "Foundry MCP Bridge" в управлении модулями

   • Не меняйте ID модуля или имя папки. Бэкенд MCP и интеграция с Claude ожидают, что модуль будет находиться в директории под названием foundry-mcp-bridge. Переименование ID в module.json нарушит маршрутизацию сокетов и не позволит Claude видеть бэкенд.

Установка MCP-сервера

# Clone repository
git clone https://github.com/adambdooley/foundry-vtt-mcp.git
cd foundry-vtt-mcp

# Install dependencies and build
npm install
npm run build

Настройка Claude Desktop

Добавьте это в ваш файл конфигурации Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "foundry-mcp": {
      "command": "node",
      "args": ["path/to/foundry-vtt-mcp/packages/mcp-server/dist/index.js"],
      "env": {
        "FOUNDRY_HOST": "localhost",
        "FOUNDRY_PORT": "31415"
      }
    }
  }
}

Запуск Claude Desktop запустит MCP-сервер.

Начало работы

1. Запустите Foundry VTT и загрузите свой мир

2. Откройте Claude Desktop

3. Общайтесь с Claude о вашем текущем загруженном мире Foundry

Пример использования

После подключения спросите Claude Desktop:

• "Покажи мне характеристики моего персонажа Кларка"

• "Найди всех гуманоидных существ с CR 12 для столкновения"

• "Создай квест о расследовании пропажи жителей деревни"

• "Сделай бросок на скрытность для Тулкаса"

• "Что находится в текущей сцене Foundry?"

• "Создай мне небольшую карту прибрежного коттеджа в Foundry"

Функции

• 36 инструментов MCP, позволяющих Claude взаимодействовать с Foundry

• Управление персонажами: Доступ к характеристикам, способностям, инвентарю и подробной информации о сущностях

• Манипуляция токенами: Перемещение, обновление, удаление токенов и управление состояниями

• Улучшенный поиск по компендиумам: Мгновенная фильтрация по CR, типу, способностям и многому другому

• Создание контента: Генерация актеров, NPC и журналов квестов

• Управление кампанией: Отслеживание многоэтапных квестов с панелями прогресса

• Интерактивная система кубиков: Отправка различных запросов на броски кубиков игрокам от Claude

• Владение актерами: Управление правами игроков на персонажей и токены

• Только для ГМ: MCP Bridge подключается только к пользователям с правами Мастера игры

• Генерация карт: Портативный бэкенд ComfyUI, который генерирует боевые карты из подсказок

• Удаленные подключения: WebRTC-соединения, инициируемые через браузер (протестировано с Google Chrome) к MCP-серверу и ComfyUI

• Установщики для Windows и Mac: Автоматизированная установка Foundry MCP Server для Claude Desktop, модуля Foundry VTT Foundry MCP Bridge и бэкенда ComfyUI с зависимостями

Инструменты MCP

• 1 get-world-info

• 2 list-scenes

• 3 get-current-scene

• 4 get-available-conditions

• 5 list-compendium-packs

• 6 list-characters

• 7 get-character

• 8 search-character-items

• 9 get-character-entity

• 10 get-token-details

• 11 toggle-token-condition (add)

• 12 toggle-token-condition (remove)

• 13 update-token

• 14 search-compendium

• 15 get-compendium-item

• 16 get-compendium-entry-full

• 17 list-creatures-by-criteria

• 18 list-journals

• 19 create-quest-journal

• 20 update-quest-journal

• 21 search-journals

• 22 link-quest-to-npc

• 23 list-actor-ownership

• 24 assign-actor-ownership

• 25 remove-actor-ownership

• 26 move-token

• 27 use-item

• 28 request-player-rolls

• 29 generate-map

• 30 check-map-status

• 31 cancel-map-job

• 32 switch-scene

• 33 create-actor-from-compendium

• 34 list-dsa5-archetypes

• 35 create-dsa5-character-from-archetype

• 36 create-campaign-dashboard

Настройки

• Улучшенный индекс существ: Кнопка настройки улучшенного индекса ведет в подменю (подробности ниже)

• Настройка службы генерации карт: Кнопка настройки службы генерации карт ведет в подменю (подробности ниже)

• Включить MCP Bridge: По умолчанию должно быть отмечено, статус должен отображаться как подключенный. Можно использовать для отключения соединения MCP Bridge внутри игры без необходимости отключать сам аддон.

• Тип соединения: Можно установить в Auto для автоматического определения типа соединения. Также можно принудительно выбрать WebRTC для интернет-соединений или Websocket для локальных соединений.

• Хост сервера Websocket: IP-адрес расположения MCP-сервера Claude Desktop. Используется только для локальных сетевых соединений Websocket. Удаленные серверы используют WebRTC. По умолчанию localhost.

• Разрешить операции записи: Это предотвратит внесение Claude любых изменений в контент мира и ограничит его только чтением

• Макс. количество актеров на запрос: Защита от создания огромного количества актеров по одному запросу. Не ограничивает количество персонажей, создаваемых несколькими запросами

• Показывать сообщения о подключении: Можно отключить баннеры сообщений о подключениях для Foundry MCP Bridge

• Автоматическое переподключение при разрыве: Будет автоматически пытаться переподключиться, если соединение потеряно

• Частота проверки соединения: Как часто будет проверяться статус соединения

Подменю "Улучшенный индекс существ"

• Перестроить индекс существ: Эта кнопка перестроит индекс существ, если возникла проблема или он не синхронизирован с изменениями в ваших компендиумах

• Включить улучшенный индекс существ: Следует оставить включенным, так как Claude создает дополнительные метаданные в файлах мира для улучшения поиска

• Автоматическая перестройка индекса при изменениях в пакетах: Экспериментальная функция, которая еще не была полностью протестирована

Подменю "Служба генерации карт"

• Статус службы: Есть три кнопки: Проверить статус, Запустить службу и Остановить службу. Эти кнопки помогают контролировать соединение от Foundry MCP Bridge к бэкенду ComfyUI, который запускается приложением Claude Desktop.

• Автозапуск службы генерации карт: Управляет тем, подключается ли соединение службы ComfyUI автоматически при запуске мира Foundry.

• Качество генерации: Управляет качеством карт, генерируемых контрольными точками SDXL в ComfyUI. Low использует 8 шагов генерации, Medium — 20 шагов, а High — 35 шагов. Контрольная точка D&D Battlemaps SDXL Upscale v1.0, используемая в этой генерации изображений, рекомендует использовать 35 шагов, но на слабых GPU или GPU без CUDA эта генерация займет несколько минут. Эти параметры позволяют найти компромисс для более быстрой генерации карт за счет качества.

Архитектура

Claude Desktop ↔ MCP Protocol ↔ MCP Server ↔ WebSocket ↔ Foundry Module ↔ Foundry VTT
                                     ↓
                              ComfyUI Service
                              (AI Map Generation)

• Модуль Foundry: Обеспечивает безопасный доступ к данным внутри Foundry VTT

• MCP-сервер: Внешний сервер Node.js, обрабатывающий связь с Claude Desktop

• Служба генерации карт: Бэкенд ComfyUI без графического интерфейса, запускаемый Claude Desktop

• API-ключи не требуются: Использует вашу существующую подписку Claude Desktop

Безопасность и права доступа

• Доступ только для ГМ: Весь функционал ограничен пользователями с правами Мастера игры

• Настраиваемые разрешения: Контролируйте, к каким данным Claude может получать доступ и изменять их

• Аутентификация на основе сессий: Использует встроенную систему аутентификации Foundry

Системные требования

• Foundry VTT: Версия 13

• Claude Desktop: Последняя версия с поддержкой MCP

• План Claude Pro/Max: Требуется для подключения к MCP-серверам

• Операционная система: Windows 10/11 (установщик) или другие ОС/ручная установка на Windows с Node.js 18+ (ручная)

• Требования к GPU: GPU с объемом видеопамяти не менее 8 ГБ

Дымовое тестирование схемы

Дымовое тестирование схемы MCP проверяет, что схемы инструментов загружаются правильно и не навязывают чрезмерно строгие значения по умолчанию для additionalProperties.

npm -w @foundry-mcp/server run build
npm run test:mcp:schema

Поддержка и разработка

• Проблемы: Сообщайте об ошибках в GitHub Issues

• YouTube-канал: Подпишитесь на обновления и уроки

• Документация: Создано с использованием TypeScript, включена полная документация

• Лицензия: Лицензия MIT (дополнительные сторонние лицензии включены для компонентов, входящих в состав установщиков)