FoundryVTT MCP Server

Ein Model Context Protocol-Server (MCP), der sich in FoundryVTT integriert und KI-Assistenten ermöglicht, über natürliche Sprache mit deinen Tabletop-Spielsitzungen zu interagieren.

Funktionen

• Würfeln – Standard-RPG-Notation mit beliebigen Formeln

• Datenabfrage – Suche und Inspektion von Akteuren, Gegenständen, Szenen, Journalen

• Spielzustand – Kampfverfolgung, Chat-Nachrichten, Benutzerpräsenz

• Inhaltsgenerierung – NSCs, Beutetabellen, Regel-Nachschlagewerke

• Weltsuche – Volltextsuche über alle Spielentitäten

• Live-Verbindung – Socket.IO lädt den vollständigen Weltzustand beim Verbinden

• MCP-Ressourcen – foundry://-URIs für direkten Datenzugriff

• Diagnose – optionale Server-Health-Überwachung (erfordert REST-API-Modul)

Related MCP server: FoundryVTT MCP Server

Schnellstart

Voraussetzungen

• Node.js 18+ (oder Bun)

• FoundryVTT-Server mit einer aktiven Welt

• MCP-kompatibler KI-Client (Claude Desktop, Claude Code, VS Code usw.)

Empfohlen: Einen dedizierten API-Benutzer erstellen

Es wird empfohlen, ein separates FoundryVTT-Benutzerkonto für den MCP-Server zu erstellen, anstatt dein eigenes GM- oder Spielerkonto zu verwenden. Das bietet bessere Sicherheit und Nachvollziehbarkeit.

In FoundryVTT:

1. Gehe zu Konfiguration → Benutzerverwaltung

2. Klicke auf Benutzer erstellen

3. Lege einen Benutzernamen (z. B. mcp-api) und ein sicheres Passwort fest

4. Weise die Rolle Assistent-GM zu (erforderlich, um Weltdaten zu lesen und Würfel zu werfen)

5. Verwende die Anmeldedaten dieses Kontos in deiner MCP-Konfiguration

Vorteile:

• Chat-Nachrichten und Aktionen des MCP-Servers werden eindeutig einem separaten Benutzer zugeordnet

• Du kannst den Zugriff widerrufen, indem du den API-Benutzer deaktivierst, ohne dein eigenes Konto zu beeinträchtigen

• Begrenzt den Schadensradius, falls Anmeldedaten jemals offengelegt werden

Installation

Direkt ausführen ohne Installation – kein Klonen erforderlich:

bunx foundryvtt-mcp

Oder mit npx:

npx -y foundryvtt-mcp

Client-Konfiguration

Claude Desktop / Claude Code

Füge zu deiner MCP-Konfiguration hinzu (claude_desktop_config.json oder .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

Füge zu deinen VS-Code-MCP-Einstellungen hinzu:

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

Entwicklungseinrichtung

Für lokale Entwicklung oder Beiträge:

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

Der Einrichtungsassistent erkennt deinen FoundryVTT-Server, testet die Konnektivität und generiert deine .env-Konfiguration.

Für manuelle Konfiguration siehe den Konfigurationsleitfaden.

Umgebungsvariablen

Verwendung

Frage deinen KI-Assistenten zum Beispiel:

• „Würfle 1d20+5 für einen Angriffswurf“

• „Zeig mir alle NSCs in dieser Szene“

• „Wie ist die aktuelle Kampf-Initiative-Reihenfolge?“

• „Durchsuche die Welt nach allem, was mit Drachen zu tun hat“

• „Generiere einen zufälligen NSC-Händler“

Verfügbare Werkzeuge

Datenzugriff

• search_actors – finde Charaktere, NSCs, Monster

• get_actor_details – detaillierte Charakterinformationen

• search_items – finde Ausrüstung, Zauber, Verbrauchsmaterialien

• get_scene_info – Details zur aktuellen Szene

• search_journals – durchsuche Notizen und Handouts

• get_journal – rufe einen bestimmten Journaleintrag ab

• get_users – liste Benutzer, Rollen und Live-Online-Status auf

• get_combat_state – Kampfzustand und Initiative-Reihenfolge

• get_chat_messages – letzter Chat-Verlauf

Schreiboperationen (erfordern FOUNDRY_WRITE_ENABLED=true)

Spielzustandsänderungen sind standardmäßig deaktiviert. Sie verwenden das Socket.IO-Protokoll modifyDocument über eine authentifizierte Sitzung, und der verbundene Benutzer benötigt GM-/Besitzer-Berechtigung. Setze FOUNDRY_WRITE_ENABLED=true, um sie zu aktivieren.

• start_combat – beginne eine neue Begegnung und setze Kämpfer aus Token ein (prüft nicht auf einen bestehenden Kampf – ein Aufruf während eines aktiven Kampfes erstellt eine zweite Begegnung)

• next_turn – rücke den aktiven Kampf zum nächsten Zug vor (springt zur nächsten Runde)

• end_combat – beende (lösche) die aktive Kampfbegegnung

• set_initiative – setze die Initiative eines Kämpfers im aktiven Kampf und verschiebe die Zugmarkierung mit dem handelnden Kämpfer, falls die Neusortierung sie verschiebt

• move_token – bewege ein Token zu neuen x/y-Koordinaten auf seiner Szene

• apply_status_effect – wende einen Statuszustand an oder entferne ihn (z. B. liegend, betäubt) auf dem Akteur eines Tokens

• update_actor_attributes – patche die system-Attribute eines Akteurs (HP, Währung, Zauberplätze, …)

• create_actor_item – füge einem Akteur ein Inline-Item hinzu

• update_actor_item – wende einen JSON-Merge-Patch auf ein Item eines Akteurs an

• delete_actor_item – entferne ein Item von einem Akteur

• create_journal_entry – erstelle einen Journaleintrag mit einer oder mehreren Textseiten (standardmäßig nur für GM; übergib visibility, um Spielern das Lesen zu ermöglichen)

Welt

• search_world – Volltextsuche über alle Spielentitäten

• get_world_summary – Überblick über den aktuellen Weltzustand

• refresh_world_data – lade Weltdaten aus FoundryVTT neu; erforderlich nach einer unterbrochenen Verbindung, deren verpasste Aktualisierungen nie in den Cache wiedergegeben werden

Spielmechanik

• roll_dice – würfle Würfel; Würfelterme (NdS) und ganze Zahlen, verbunden mit +/-, wobei nicht unterstützte Notationen (4d6kh3, 1d20r1, *) abgelehnt statt verworfen werden. Klammern sind der einzige Transportunterschied: FoundryVTT wertet sie aus, wenn FOUNDRY_API_KEY gesetzt ist, der lokale Würfler lehnt sie andernfalls ab

• lookup_rule – Stub: gibt einen vorlagenbasierten Platzhalter zurück, konsultiert keine Regelquelle

Inhaltsgenerierung

• generate_npc – generiere NSC-Text (wird nicht in die Welt geschrieben)

• generate_loot – generiere Schatztext für eine Stufe (wird nicht in die Welt geschrieben)

Diagnose (erfordert REST-API-Modul)

• get_recent_logs – rufe gefilterte FoundryVTT-Protokolle ab

• search_logs – durchsuche Protokolle nach Muster und liste die übereinstimmenden Einträge auf

• get_system_health – Server-Health-Status mit Versionen, Benutzer-/Modulzahlen, Speicher und Protokollfehlerzahlen (keine CPU- oder Datenträgermetriken)

• diagnose_errors – Stub: gibt eine feste „keine Fehler erkannt“-Zusammenfassung zurück

• get_health_status – umfassende Health-Diagnose; kennzeichnet die Weltsnapshot, wenn der Cache aufgehört hat, Live-Änderungen zu verfolgen

Verfügbare Ressourcen

• foundry://actors – alle Akteure in der Welt

• foundry://items – alle Gegenstände in der Welt

• foundry://scenes – alle Szenen

• foundry://scenes/current – aktuelle aktive Szene

• foundry://journals – alle Journaleinträge

• foundry://users – Online-Benutzer

• foundry://combat – aktiver Kampfzustand; combatants sind in Initiative-Reihenfolge, sodass combat.turn sie direkt indiziert

• foundry://world/settings – Welt- und Kampagneneinstellungen

• foundry://system/diagnostics – Systemdiagnose (erfordert REST-API-Modul)

Fehlerbehebung

Die Konnektivitäts- und Einrichtungshilfen befinden sich im Quellbaum (nicht im veröffentlichten bin), also führe sie aus einem Entwicklungs-Checkout aus:

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

Ausführlicher Leitfaden: TROUBLESHOOTING.md

Entwicklung

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)

Siehe Entwicklungsleitfaden für Projektstruktur, Hinzufügen von Werkzeugen, Testen und Erstellen.

Roadmap

Siehe Feature-Tracker für abgeschlossene und geplante Funktionen.

Mitwirken

Siehe CONTRIBUTING.md.

Lizenz

MIT-Lizenz – siehe LICENSE für Details.

Unterstützung

• Probleme: GitHub Issues

• Discord: FoundryVTT Discord #api-development

• Dokumentation: FoundryVTT API

Danksagungen

• Das FoundryVTT-Team für die hervorragende VTT-Plattform

• Anthropic für das Model Context Protocol

• Die Tabletop-Gaming-Community für Inspiration und Feedback