FoundryVTT MCP Server

Un servidor de Model Context Protocol (MCP) que se integra con FoundryVTT, permitiendo a los asistentes de IA interactuar con tus sesiones de juegos de mesa mediante lenguaje natural.

Características

• Lanzamiento de dados — notación estándar de RPG con cualquier fórmula

• Consulta de datos — busca e inspecciona actores, objetos, escenas, diarios

• Estado del juego — seguimiento de combate, mensajes de chat, presencia de usuarios

• Generación de contenido — PNJs, tablas de botín, consultas de reglas

• Búsqueda en el mundo — búsqueda de texto completo en todas las entidades del juego

• Conexión en vivo — Socket.IO carga el estado completo del mundo al conectar

• Recursos MCP — URIs foundry:// para acceso directo a datos

• Diagnósticos — monitoreo opcional de salud del servidor (requiere módulo de API REST)

Related MCP server: FoundryVTT MCP Server

Inicio rápido

Requisitos previos

• Node.js 18+ (o Bun)

• Servidor de FoundryVTT en ejecución con un mundo activo

• Cliente de IA compatible con MCP (Claude Desktop, Claude Code, VS Code, etc.)

Recomendado: Crear un usuario de API dedicado

Se recomienda crear una cuenta de usuario de FoundryVTT separada para el servidor MCP en lugar de usar tu propia cuenta de GM o de jugador. Esto proporciona mejor seguridad y auditabilidad.

En FoundryVTT:

1. Ve a Configuración → Gestión de usuarios

2. Haz clic en Crear usuario

3. Establece un nombre de usuario (por ejemplo, mcp-api) y una contraseña segura

4. Asigna el rol de GM asistente (necesario para leer datos del mundo y lanzar dados)

5. Usa las credenciales de esta cuenta en tu configuración de MCP

Beneficios:

• Los mensajes de chat y las acciones del servidor MCP se atribuyen claramente a un usuario separado

• Puedes revocar el acceso deshabilitando el usuario de API sin afectar tu propia cuenta

• Limita el radio de impacto si las credenciales alguna vez se exponen

Instalación

Ejecuta directamente sin instalar — no se necesita clonar:

bunx foundryvtt-mcp

O con npx:

npx -y foundryvtt-mcp

Configuración del cliente

Claude Desktop / Claude Code

Añade a tu configuración de MCP (claude_desktop_config.json o .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

Añade a tu configuración de MCP de VS Code:

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

Configuración de desarrollo

Para desarrollo local o contribuciones:

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

El asistente de configuración detectará tu servidor de FoundryVTT, probará la conectividad y generará tu configuración .env.

Para configurar manualmente, consulta la Guía de configuración.

Variables de entorno

Uso

Pregunta a tu asistente de IA cosas como:

• "Lanza 1d20+5 para una tirada de ataque"

• "Muéstrame todos los PNJs en esta escena"

• "¿Cuál es el orden de iniciativa actual del combate?"

• "Busca en el mundo cualquier cosa relacionada con dragones"

• "Genera un mercader PNJ aleatorio"

Herramientas disponibles

Acceso a datos

• search_actors — encuentra personajes, PNJs, monstruos

• get_actor_details — información detallada del personaje

• search_items — encuentra equipo, hechizos, consumibles

• get_scene_info — detalles de la escena actual

• search_journals — busca notas y documentos

• get_journal — recupera una entrada de diario específica

• get_users — lista usuarios, roles y estado en línea en vivo

• get_combat_state — estado del combate y orden de iniciativa

• get_chat_messages — historial de chat reciente

Operaciones de escritura (requieren FOUNDRY_WRITE_ENABLED=true)

Las mutaciones del estado del juego están deshabilitadas por defecto. Usan el protocolo Socket.IO modifyDocument sobre una sesión autenticada, y el usuario conectado necesita permiso de GM/propietario. Establece FOUNDRY_WRITE_ENABLED=true para habilitarlas.

• start_combat — inicia un nuevo encuentro, sembrando combatientes desde tokens (no comprueba si hay un combate existente — llamarlo durante uno activo crea un segundo encuentro)

• next_turn — avanza el combate activo al siguiente turno (vuelve a la siguiente ronda)

• end_combat — finaliza (elimina) el encuentro de combate activo

• set_initiative — establece la iniciativa de un combatiente en el combate activo, moviendo el marcador de turno con el combatiente actuante si el reordenamiento los desplaza

• move_token — mueve un token a nuevas coordenadas x/y en su escena

• apply_status_effect — aplica o elimina una condición de estado (p. ej., tumbado, aturdido) en el actor de un token

• update_actor_attributes — parchea los atributos system de un actor (PG, moneda, espacios de conjuro, …)

• create_actor_item — añade un objeto en línea a un actor

• update_actor_item — aplica un parche de fusión JSON al objeto de un actor

• delete_actor_item — elimina un objeto de un actor

• create_journal_entry — crea una entrada de diario con una o más páginas de texto (solo GM por defecto; pasa visibility para permitir que los jugadores la lean)

Mundo

• search_world — búsqueda de texto completo en todas las entidades del juego

• get_world_summary — resumen del estado actual del mundo

• refresh_world_data — recarga los datos del mundo desde FoundryVTT; necesario después de una conexión caída, cuyas actualizaciones perdidas nunca se reproducen en la caché

Mecánicas del juego

• roll_dice — lanza dados; términos de dados (NdS) y números enteros unidos por +/-, con notación no soportada (4d6kh3, 1d20r1, *) rechazada en lugar de ignorada. Los paréntesis son la única diferencia de transporte: FoundryVTT los evalúa cuando FOUNDRY_API_KEY está configurada, el lanzador local los rechaza en caso contrario

• lookup_rule — stub: devuelve un marcador de posición con plantilla, no consulta ninguna fuente de reglas

Generación de contenido

• generate_npc — genera texto de PNJ (no se escribe en el mundo)

• generate_loot — genera texto de tesoro para un nivel (no se escribe en el mundo)

Diagnósticos (requiere módulo de API REST)

• get_recent_logs — recupera registros de FoundryVTT filtrados

• search_logs — busca registros por patrón, listando las entradas coincidentes

• get_system_health — estado de salud del servidor con versiones, recuentos de usuarios/módulos, memoria y recuentos de errores de registro (sin métricas de CPU o disco)

• diagnose_errors — stub: devuelve un resumen fijo de "no se detectaron errores"

• get_health_status — diagnósticos de salud completos; marca la instantánea del mundo cuando la caché ha dejado de seguir los cambios en vivo

Recursos disponibles

• foundry://actors — todos los actores del mundo

• foundry://items — todos los objetos del mundo

• foundry://scenes — todas las escenas

• foundry://scenes/current — escena activa actual

• foundry://journals — todas las entradas de diario

• foundry://users — usuarios en línea

• foundry://combat — estado del combate activo; combatants están en orden de iniciativa, por lo que combat.turn los indexa directamente

• foundry://world/settings — configuración del mundo y de la campaña

• foundry://system/diagnostics — diagnósticos del sistema (requiere módulo de API REST)

Solución de problemas

Los ayudantes de conectividad y configuración se incluyen en el árbol de fuentes (no en el bin publicado), así que ejecútalos desde un checkout de desarrollo:

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

Guía detallada: TROUBLESHOOTING.md

Desarrollo

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)

Consulta la Guía de desarrollo para la estructura del proyecto, añadir herramientas, pruebas y compilación.

Hoja de ruta

Consulta el Seguimiento de funciones para funciones completadas y planificadas.

Contribuciones

Consulta CONTRIBUTING.md.

Licencia

Licencia MIT — consulta LICENSE para más detalles.

Soporte

• Problemas: GitHub Issues

• Discord: FoundryVTT Discord #api-development

• Documentación: FoundryVTT API

Agradecimientos

• Equipo de FoundryVTT por la excelente plataforma VTT

• Anthropic por el Model Context Protocol

• La comunidad de juegos de mesa por la inspiración y los comentarios