Foundry VTT MCP Bridge

Conecta Foundry VTT a Claude Desktop para la gestión de campañas mediante IA a través del Protocolo de Contexto de Modelos (MCP). Actualmente es compatible con Dungeons and Dragons Quinta Edición y Pathfinder Segunda Edición. La mayoría de las herramientas MCP son independientes del sistema, pero las herramientas de creación de personajes y búsqueda en compendios solo funcionan con D&D5e y PF2E.

Descripción general

El puente Foundry MCP permite conversaciones naturales con IA sobre los datos de tu partida en Foundry VTT:

• Creación de misiones: Crea misiones a partir de sugerencias que incorporan lo que ya existe en tu mundo y diarios

• Gestión de personajes: Consulta estadísticas, habilidades e información de los personajes

• Búsqueda en compendios: Encuentra objetos, hechizos y criaturas usando lenguaje natural

• Creación de contenido: Genera actores, PNJs y diarios de misiones a partir de simples sugerencias

• Información de escenas: Accede a los datos de la escena actual y a los detalles del mundo

• Coordinación de dados: Solicitudes de tiradas interactivas con selección de jugadores

• Gestión de campañas: Seguimiento de misiones de varias partes y campañas

• Generación de mapas: Crea mapas a partir de sugerencias y súbelos automáticamente a las escenas en Foundry VTT usando el componente opcional ComfyUI

Este proyecto fue creado con la ayuda de Claude Code. Si te gusta este proyecto, considera apoyarlo en Patreon.

Related MCP server: Coreflux MCP Server

Instalación

Requisitos previos

• Foundry VTT v13

• Claude Desktop con soporte para MCP

• Windows (para el instalador automático) o Node.js 18+ para la instalación manual

Opción 1: Instalador de Windows

Guía en vídeo para el instalador de Windows

1. Descarga el archivo FoundryMCPServer-Setup-vx.x.x.exe más reciente desde Releases

2. Ejecuta el instalador; este realizará lo siguiente:

   • Instalará el servidor MCP con el entorno de ejecución de Node.js incluido

   • Configurará los ajustes del servidor MCP de Claude Desktop

   • Opcionalmente, instalará el módulo de Foundry y la generación de mapas ComfyUI en tu instalación de VTT

   • Elegirá la versión de Cuda para tu tipo de GPU durante la instalación

3. Reinicia Claude Desktop

4. Habilita "Foundry MCP Bridge" en la Gestión de módulos de Foundry

Opción 2: Instalador de Mac

1. Descarga el archivo FoundryMCPServer-vx.x.x.dmg más reciente desde Releases

2. Ejecuta el instalador del paquete dentro del dmg; este realizará lo siguiente:

   • Abre el DMG y haz doble clic en el instalador PKG

   • Configurará los ajustes del servidor MCP de Claude Desktop

   • Opcionalmente, instalará el módulo de Foundry y la generación de mapas ComfyUI en tu instalación de Foundry VTT

3. Reinicia Claude Desktop

4. Habilita "Foundry MCP Bridge" en la Gestión de módulos de Foundry

Opción 3: Instalación manual

Instalar el módulo de Foundry

1. Abre Foundry VTT v13

2. Selecciona instalar módulo en el menú de complementos de Foundry

3. En la parte inferior de la ventana, añade la URL del manifiesto como: https://github.com/adambdooley/foundry-vtt-mcp/blob/master/packages/foundry-module/module.json y haz clic en instalar

4. Habilita "Foundry MCP Bridge" en la Gestión de módulos

   • No cambies el ID del módulo ni el nombre de la carpeta. Tanto el backend de MCP como la integración con Claude esperan que el módulo resida en un directorio llamado foundry-mcp-bridge. Renombrar el ID en module.json rompe el enrutamiento de sockets e impide que Claude vea el backend.

Instalar el servidor 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

Configurar Claude Desktop

Añade esto a tu archivo de configuración de 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"
      }
    }
  }
}

Al iniciar Claude Desktop, se iniciará el servidor MCP.

Primeros pasos

1. Inicia Foundry VTT y carga tu mundo

2. Abre Claude Desktop

3. Chatea con Claude sobre tu mundo de Foundry cargado actualmente

Ejemplo de uso

Una vez conectado, pregúntale a Claude Desktop:

• "Muéstrame las estadísticas de mi personaje Clark"

• "Encuentra todas las criaturas humanoides de VD 12 para un encuentro"

• "Crea una misión sobre investigar la desaparición de aldeanos"

• "Haz una tirada de sigilo para Tulkas"

• "¿Qué hay en la escena actual de Foundry?"

• "Créame un mapa pequeño de una cabaña junto al río en Foundry"

Características

• 36 herramientas MCP que permiten a Claude interactuar con Foundry

• Gestión de personajes: Accede a estadísticas, habilidades, inventario e información detallada de entidades

• Manipulación de tokens: Mueve, actualiza, elimina tokens y gestiona condiciones de estado

• Búsqueda mejorada en compendios: Filtrado instantáneo por VD, tipo, habilidades y más

• Creación de contenido: Genera actores, PNJs y diarios de misiones

• Gestión de campañas: Seguimiento de misiones de varias partes con paneles de progreso

• Sistema de dados interactivo: Envía diferentes solicitudes de tiradas de dados a los jugadores desde Claude

• Propiedad de actores: Gestiona los permisos de los jugadores para personajes y tokens

• Solo para el DJ: El puente MCP solo se conecta a usuarios con rol de Director de Juego

• Generación de mapas: Un backend portátil de ComfyUI que genera mapas de batalla a partir de sugerencias

• Conexiones remotas: Conexiones WebRTC iniciadas a través del navegador (probado con Google Chrome) al servidor MCP y ComfyUI

• Instaladores para Windows y Mac: Instalación automatizada del servidor Foundry MCP para Claude Desktop, el módulo Foundry VTT del puente Foundry MCP y el backend de ComfyUI con sus dependencias

Herramientas 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

Ajustes

• Índice de criaturas mejorado: Configurar el botón de Índice mejorado lleva al submenú de Índice de criaturas mejorado (detalles a continuación)

• Configuración del servicio de generación de mapas: Configurar el botón de Generación de mapas lleva al submenú del Servicio de generación de mapas (detalles a continuación)

• Habilitar puente MCP: Debería estar marcado por defecto y el estado debería mostrarse como conectado. Se puede usar para desactivar la conexión del puente MCP dentro del juego sin necesidad de desactivar el complemento en sí.

• Tipo de conexión: Se puede establecer en Automático para la detección automática del tipo de conexión. También se puede configurar para forzar WebRTC para conexiones a Internet o Websocket para conexiones locales.

• Host del servidor Websocket: Dirección IP de la ubicación del servidor MCP de Claude Desktop. Solo se usa para conexiones websocket de red local. Los servidores remotos usan WebRTC. Por defecto es localhost.

• Permitir operaciones de escritura: Esto evitará que Claude realice cambios en el contenido del mundo y lo restringirá solo a lectura

• Máximo de actores por solicitud: Es una medida de seguridad para evitar que se cree una cantidad masiva de actores a partir de una sola solicitud. No limita la cantidad de personajes creados por múltiples solicitudes

• Mostrar mensajes de conexión: Esto puede desactivar los mensajes de banner para las conexiones del puente Foundry MCP

• Reconexión automática al desconectarse: Intentará reconectarse automáticamente si se pierde la conexión

• Frecuencia de comprobación de conexión: Con qué frecuencia comprobará el estado de la conexión

Submenú de Índice de criaturas mejorado

• Reconstruir índice de criaturas: Este botón reconstruirá el índice de criaturas si hay algún problema o si no está sincronizado con los cambios en tus compendios

• Habilitar índice de criaturas mejorado: Esto debería dejarse activado, ya que Claude crea metadatos adicionales en los archivos del mundo para mejorar las búsquedas

• Reconstruir índice automáticamente al cambiar paquetes: Función experimental que aún no se ha probado completamente

Submenú del Servicio de generación de mapas

• Estado del servicio: Hay tres botones para Comprobar estado, Iniciar servicio y Detener servicio. Estos botones ayudan a supervisar y controlar la conexión desde el puente Foundry MCP al backend de ComfyUI, que es iniciado por la aplicación Claude Desktop.

• Iniciar automáticamente el servicio de generación de mapas: Controla si la conexión al servicio ComfyUI se conecta automáticamente al iniciar el mundo de Foundry.

• Calidad de generación: Controla la calidad de los mapas generados por los puntos de control SDXL con ComfyUI. Bajo usa 8 pasos de generación, Medio usa 20 pasos y Alto usa 35 pasos. El punto de control D&D Battlemaps SDXL Upscale v1.0 utilizado en esta generación de imágenes recomienda usar 35 pasos, pero en GPUs de gama baja o GPUs sin CUDA, esta generación tardará varios minutos. Estas opciones pueden ofrecerte un equilibrio para generar mapas más rápido a costa de la calidad.

Arquitectura

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

• Módulo de Foundry: Proporciona acceso seguro a los datos dentro de Foundry VTT

• Servidor MCP: Servidor externo de Node.js que gestiona la comunicación con Claude Desktop

• Servicio de generación de mapas: Un backend de ComfyUI sin interfaz gráfica que es generado por Claude Desktop

• No se requieren claves API: Utiliza tu suscripción existente a Claude Desktop

Seguridad y permisos

• Acceso solo para el DJ: Toda la funcionalidad está restringida a usuarios con rol de Director de Juego

• Permisos configurables: Controla a qué datos puede acceder y modificar Claude

• Autenticación basada en sesiones: Utiliza el sistema de autenticación integrado de Foundry

Requisitos del sistema

• Foundry VTT: Versión 13

• Claude Desktop: Versión más reciente con soporte para MCP

• Plan Claude Pro/Max: Requerido para conectarse a servidores MCP

• Sistema operativo: Windows 10/11 (instalador), u otros sistemas operativos/instalación manual en Windows con Node.js 18+ (manual)

• Requisitos de GPU: Una GPU con al menos 8 GB de VRAM

Prueba de humo del esquema

La prueba de humo del esquema MCP verifica que los esquemas de las herramientas se carguen correctamente y no impongan valores predeterminados de additionalProperties demasiado estrictos.

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

Soporte y desarrollo

• Problemas: Informa de errores en GitHub Issues

• Canal de YouTube: Suscríbete para obtener actualizaciones y tutoriales

• Documentación: Creado con TypeScript, incluye documentación completa

• Licencia: Licencia MIT (se incluyen licencias adicionales de terceros para los componentes incluidos en los instaladores)