FoundryVTT MCP Server

Ein umfassender, produktionsreifer Model Context Protocol-Server (MCP) für Foundry Virtual Tabletop (FoundryVTT).

Dieser Server befähigt KI-Assistenten (Claude Desktop, Claude Code, Oh My Pi, VS Code, Cursor usw.) dazu, innerhalb von FoundryVTT als vollwertige, autonome Co-GMs und GM-Assistenten zu agieren. Er bietet vollständigen Lese- und Schreibzugriff auf Spielmechaniken, Akteure, Gegenstände, Token, Kampfbegegnungen, Canvas-Platzierungen (Wände, Lichter, Geräusche, Vorlagen, Zeichnungen, Notizen, Kacheln), Wiedergabelisten, Makros, Würfeltabellen, Kompendien, Welteinstellungen und Live-Canvas-Rendering.

🌟 Wichtigste Highlights & Fähigkeiten (111 Tools)

• 👁️ Echtzeit-Eventstream & Aktivitätsprotokoll (watch_events): Ereigniswahrnehmung ohne Polling über Socket.IO modifyDocument und Push-Nachrichten der Begleitbrücke. Ein KI-Spielleiteragent kann per Long-Polling auf einen cursor-adressierten Stream (cursor, waitMs, excludeSelf, types, sceneId) zugreifen, um sofort zu reagieren, wenn Spieler chatten, Token bewegen, den Kampf vorantreiben, Türen umschalten oder Ziele auswählen.

• 🎲 Spielmechaniken & Interaktiver Chat: Würfle mit standardmäßiger oder komplexer Drop/Keep-Notation (4d6kh3, 1d20r1). Würfle und poste interaktive, klickbare Chat-Karten direkt in das Foundry-Chatprotokoll über die Begleitbrücke (roll_and_post).

• 🗺️ Volle Canvas- & Raumkontrolle: Erstelle, inspiziere, aktualisiere und entferne alle Canvas-Platzierungstypen:

  • Szenenregionen (v12+): create_region, delete_region, list_regions mit geometrischen Formen (rectangle, circle, ellipse, polygon) und automatisierten Auslöseverhalten.

  • Wände & Türen: Standardwände, Türen (öffnen/schließen/verriegeln), Geheimtüren, Fenster, ätherische Wände und benutzerdefinierte Koordinaten (create_wall, list_walls, set_door_state).

  • Umgebungslichter: Platzierung per Koordinate oder Rasterzelle, Radien für schwach/hell, Animationseffekte, Farbschwellen (create_light, update_light, delete_light, list_lights).

  • Umgebungsgeräusche: Audiotitel, Radien, Lautstärke, Wiederholungsmodi (create_sound, delete_sound, list_sounds).

  • Messvorlagen: Kegel-, Kreis-, Strahl- und Rechteck-Markierungen für Zauberwirkungsbereiche mit Richtungsrotation und Farben (create_template, delete_template, list_templates).

  • Zeichnungen: Freihand- und geometrische Formen, Linien-/Füllstile und Textanmerkungen (create_drawing, delete_drawing, list_drawings).

  • Kartennotizen & Pins: Wahrzeichen-Markierungen, die mit Journaleinträgen verknüpft sind, oder eigenständige Beschriftungen (create_note, delete_note, list_notes).

  • Kacheln & Requisiten: platziere dekorative Kacheln und Hintergründe (create_tile, delete_tile, list_tiles).

  • Canvas-Viewport-Erfassung: erstelle einen Screenshot des GM-Canvas-Viewports mit eingebranntem Koordinatenraster-Overlay ([col,row]) über capture_scene.

  • Zielerfassung & Animierte Pings: lenke die Aufmerksamkeit der Spieler mit animierten Kamera-Pings (ping_canvas) und zeige/setze Token-Zielmarkierungen (set_target, get_targets).

• 🧙 Token- & Akteurskontrolle:

  • A*-Pfadfindungs-Bewegung: Token navigieren um Wände herum und öffnen automatisch geschlossene Türen entlang ihres Pfads (move_token_pathfind).

  • Token-Sicht & Beleuchtung: konfiguriere Sichtweiten, Sichtmodi, schwach/hell emittiertes Licht und Sicht-Erkennungswinkel (update_token_vision).

  • Generalisierte ActiveEffects: erstelle, aktualisiere, lösche und inspiziere mechanische Buffs/Debuffs mit Attributänderungen (key, mode, value, priority) und Dauern (rounds, seconds, turns) auf Top-Level- oder synthetischen, nicht verknüpften Token-Akteuren (create_actor_effect, update_actor_effect, delete_actor_effect, list_actor_effects).

  • Statusbedingungen: wende systemagnostische Statusbedingungen an/entferne sie (apply_status_effect).

  • Kompendium-Akteur- & Gegenstandsimport: importiere vollständige NSC/Monster-Dokumente aus Kompendiumspaketen mit automatischer Fehlerbehebung pro Gegenstand (import_compendium_actor) oder importiere bestimmte Gegenstände in Akteursinventare (create_actor_item).

  • Systemattribut-Mutationen: patche Akteur-Systemdaten (HP, temporäre HP, Währung, Ressourcen, Zauberplätze) mithilfe von JSON-Merge-Patches (update_actor_attributes).

• ⚔️ Kampfbegegnungsverwaltung: Erstelle Begegnungen, befülle Kämpfer aus Token, verwalte Initiativreihenfolgen, schreite Züge/Runden voran, verfolge aktive Kämpfer, pausiere/setze die Spieluhr fort (set_pause) und beende Begegnungen.

• 📜 Weltdokumente & Organisation:

  • Ordner: verwalte hierarchische Ordnerstrukturen für Akteure, Gegenstände, Journale und Szenen (create_folder, list_folders).

  • Makros: inspiziere, erstelle und lösche Skript-/Chat-Makros (create_macro, list_macros, delete_macro).

  • Wiedergabelisten & Audio: erstelle Wiedergabelisten mit mehreren Titeln, steuere die Wiedergabe (Wiedergabe, Pause, Stopp) und passe Titelzustände an (create_playlist, set_playlist_state, list_playlists).

  • Würfeltabellen: erstelle Tabellen mit automatischer sequenzieller Bereichsverteilung (1dN) und ziehe Live-Ergebnisse (create_roll_table, roll_table, list_roll_tables).

  • Dokumentbesitz & Benutzerrollen: konfiguriere granulare Dokumentberechtigungen (set_document_ownership) und Benutzerrollen mit Sperrschutz gegen eigene Herabstufung (set_user_role).

  • Welteinstellungen: inspiziere und aktualisiere Modul- und Systemeinstellungen sicher mit integriertem Schutz vor Beschädigung der Kern-Engine (get_world_setting, set_world_setting).

  • Asset-Uploads: lade Bilder, Token und Audiodateien direkt in Foundrys Data/-Speicher über den nativen FilePicker oder das lokale Dateisystem hoch (upload_asset).

• 🌫️ Szenen-, Wetter- & Erkundungsverwaltung: Wechsle aktive Szenen, passe Dunkelheitsgrade an, schalte globale Beleuchtung um, stelle Umgebungswettereffekte ein (set_scene_weather) und setze die Fog-of-War-Erkundung zurück (reset_fog).

• 🔍 Regel- & Kompendiumssuche: Durchsuche Weltdokumente, Kompendiumspakete und Regeltexte mit kontextuellen Ausschnitten (search_compendium_content, lookup_rule).

Related MCP server: Foundry VTT MCP Bridge

🏗️ Architektur

Der Server verwendet eine hybride Architektur, um Echtzeit-Reaktionsfähigkeit und tiefe Integration in die Spiel-Engine zu bieten:

┌─────────────────────────────────────────────────────────────┐
│                    AI Assistant / MCP Client                │
│             (Claude Desktop, Oh My Pi, VS Code)             │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP (stdio)
┌──────────────────────────────▼──────────────────────────────┐
│                    FoundryVTT MCP Server                    │
├──────────────────────────────┬──────────────────────────────┤
│  In-Memory World Cache       │  A* Pathfinding Router       │
│  (Live Socket.IO Sync)       │  Dice Notation Engine        │
└──────────────┬───────────────┴──────────────┬───────────────┘
               │ Socket.IO (Port 30000)       │ WebSocket (Port 31415)
               │ (modifyDocument / Events)    │ (Bridge Protocol)
┌──────────────▼──────────────────────────────▼───────────────┐
│                    FoundryVTT Game Engine                   │
│  ┌────────────────────────┐    ┌─────────────────────────┐  │
│  │   Active World & Data  │    │  Companion Module       │  │
│  │   (Actors, Scenes, …)  │    │  (foundryvtt-mcp-bridge)│  │
│  └────────────────────────┘    └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

1. Socket.IO-Primärverbindung: Verbindet sich als authentifizierter Benutzer (mcp-api) mit FoundryVTT. Synchronisiert und cached den Weltzustand automatisch und ermöglicht so sofortige Nachschlagevorgänge und hochfrequente Dokumentmutationen über das modifyDocument-Protokoll.

2. Begleitmodul-Brücke (foundryvtt-mcp-bridge): Ein leichtgewichtiges Foundry-Modul, das im Browser läuft und Canvas-gebundene Operationen ausführt (PIXI-Canvas-Screenshot mit Raster-Overlay, natives Rendern von Roll-Chatkarten, Introspection des Dokumentschemas und Extraktion von Kompendiumselementen).

3. Optionales REST-API-Modul: Bietet Serverdiagnose, Protokollabruf und Statusberichte, wenn das lokale REST-Modul installiert ist.

🚀 Schnellstart

1. Voraussetzungen

• Node.js 18+ oder Bun

• FoundryVTT v11+ / v12+ mit einer aktiven Welt

• Ein dediziertes Foundry-Benutzerkonto mit der Rolle Gamemaster oder Assistant GM

2. Dedizierten Foundry-Benutzer konfigurieren

In FoundryVTT:

1. Öffne Konfiguration → Benutzerverwaltung

2. Klicke auf Benutzer erstellen

3. Setze Benutzername: mcp-api, Passwort: mcp (oder deine Wahl)

4. Rolle: Gamemaster (oder Assistant GM mit aktivierten Schreibberechtigungen)

3. Begleitmodul installieren (Empfohlen)

Kopiere den Ordner foundry-module aus diesem Repository in dein FoundryVTT-Verzeichnis Data/modules/:

# Windows
cp -r foundry-module "%LOCALAPPDATA%/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

# macOS
cp -r foundry-module "~/Library/Application Support/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

# Linux
cp -r foundry-module "~/.local/share/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

Gehe in FoundryVTT zu Module verwalten und aktiviere FoundryVTT MCP Bridge.

⚙️ Konfiguration & Client-Einrichtung

Umgebungsvariablen

Claude Desktop Konfiguration

Füge zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "foundryvtt": {
      "command": "node",
      "args": ["<PATH_TO_REPO>/dist/index.js"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "mcp-api",
        "FOUNDRY_PASSWORD": "mcp",
        "FOUNDRY_WRITE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_PORT": "31415"
      }
    }
  }
}

Konfiguration für Oh My Pi

Füge zu ~/.omp/agent/mcp.json (oder ~/.omp/mcp.json) hinzu:

{
  "mcpServers": {
    "foundryvtt": {
      "type": "stdio",
      "command": "node",
      "args": ["<PATH_TO_REPO>/dist/index.js"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "mcp-api",
        "FOUNDRY_PASSWORD": "mcp",
        "FOUNDRY_WRITE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_PORT": "31415"
      },
      "timeout": 60000
    }
  }
}

🛠️ Werkzeugkatalog (111 Tools)

1. Echtzeit-Ereigniswahrnehmung

• watch_events — Long-Polling auf einem cursor-adressierten Aktivitätsprotokoll (cursor, waitMs, limit, kinds, types, actions, sceneId, excludeSelf), das Dokumentübertragungen und Canvas-Aktivitäten ohne Polling erfasst.

2. Canvas- & räumliche Platzierungen

• create_region / delete_region / list_regions — verwalte Szenenregionen (v12+) mit geometrischen Formen (rectangle, circle, ellipse, polygon) und automatisierten Verhaltensweisen.

• create_wall / delete_wall / list_walls / set_door_state — vollständige Verwaltung von Wand- und Türgeometrien.

• create_light / update_light / delete_light / list_lights — Steuerung der Umgebungsbeleuchtung (Radien, Farben, Animationen).

• create_sound / delete_sound / list_sounds — Platzierung von Umgebungsaudio auf Canvas-Szenen.

• create_template / delete_template / list_templates — Wirkungsbereichsvorlagen für Zauber und Effekte.

• create_drawing / delete_drawing / list_drawings — Kartenformen, Zonen und Textanmerkungen.

• create_note / delete_note / list_notes — Karten-Pins und Wahrzeichen-Markierungen.

• create_tile / delete_tile / list_tiles — dekorative Kacheln und Karten-Requisiten.

• capture_scene — erstelle einen Screenshot der aktiven Szenen-Canvas mit eingebranntem Koordinatenraster-Overlay.

• ping_canvas — sende einen animierten Canvas-Ping an bestimmten Pixelkoordinaten.

• find_open_cells — durchsuche Szenen nach nicht blockierten Rasterzellen, die sich für die Platzierung von Token/Requisiten eignen.

• list_scene_assets — entdecke Kartenhintergründe, Token-Grafiken und Audiodateien mit geparsten Tags und Abmessungen.

• upload_asset — lade Bild-/Audiodateien über den FilePicker oder das lokale Dateisystem in Foundrys Data/-Verzeichnis hoch.

3. Token & Bewegung

• spawn_token — platziert Akteur-Tokens auf Szenen mit benutzerdefinierter Größe, Höhe und Koordinaten.

• delete_token — entfernt Tokens von Szenen, ohne den zugrunde liegenden Akteur zu löschen.

• list_tokens — listet platzierte Tokens auf aktiven oder bestimmten Szenen.

• move_token — teleportiert ein Token zu exakten Pixelkoordinaten.

• move_token_pathfind — bewegt Tokens mit A*-Hindernisvermeidung um Wände herum mit automatischem Türöffnen.

• move_tokens — bewegt mehrere Tokens gleichzeitig in Stapelverarbeitung.

• set_target / get_targets — setzt und prüft Token-Zielmarkierungen über verbundene Benutzer hinweg.

• update_token_vision — konfiguriert Sichtweiten, Sichtmodi, gedimmte/helle Lichtquellen und Winkel.

• apply_status_effect — schaltet einfache Statuszustände um (liegend, betäubt, geblendet, unsichtbar usw.).

4. Akteure & Inventar

• create_world_actor / create_full_actor / delete_world_actor — erstellt und löscht Akteur-Dokumente.

• import_compendium_actor — importiert komplette NSCs/Monster aus Kompendium-Paketen mit eingebetteten Gegenständen und automatischer Fehlerbehebung.

• search_actors — durchsucht Akteure nach Name und Typ mit Cursor-Paginierung.

• get_actor_details — ruft Akteur-Systemdaten, Statistiken, Attribute und Gesundheit ab.

• update_actor_attributes — ändert verschachtelte Systemdaten mithilfe von Punktpfaden (attributes.hp.value, currency.gp).

• get_actor_inventory — listet Besitzgegenstände mit vollständigen Systemeigenschaften.

• create_actor_item — erstellt Inline-Gegenstände ODER importiert direkt aus Kompendium-Paketen (source: { type: 'compendium', compendiumId, itemId }).

• update_actor_item — wendet JSON-Merge-Patches auf Besitzgegenstände an.

• delete_actor_item — löscht bestimmte Gegenstände aus Akteur-Inventaren.

• create_actor_effect / update_actor_effect / delete_actor_effect / list_actor_effects — Allzweck-ActiveEffects mit mechanischen Änderungen (key, mode, value, priority) und Dauern auf Top-Level- oder synthetischen, nicht verknüpften Token-Akteuren.

5. Kampfbegegnungen

• start_combat — erstellt Begegnungen und befüllt Kämpfer aus Szenen-Tokens.

• get_combat_state — ruft Zugreihenfolge, TP, RK und Rundenanzahl der Kämpfer ab.

• set_initiative — setzt Initiativewerte der Kämpfer und ordnet Züge neu.

• next_turn — rückt den Zug-Tracker vor (behandelt Rundeninkremente und überspringt besiegte Kämpfer).

• set_pause — pausiert oder setzt die Spieluhr fort.

• end_combat — beendet aktive Begegnungen.

6. Weltdokumente & Organisation

• list_folders / create_folder — organisiert Akteure, Gegenstände, Journale und Szenen in verschachtelten Ordnern.

• list_macros / create_macro / delete_macro — verwaltet Skript- und Chat-Makro-Dokumente.

• list_playlists / create_playlist / set_playlist_state / delete_playlist — Audio-Playlist- und Soundsteuerung.

• create_roll_table / delete_roll_table / roll_table / list_roll_tables — Tabellenerstellung und Ergebniswürfe.

• get_world_setting / set_world_setting — prüft und ändert System-/Modul-Einstellungen mit Kernschutz.

• set_document_ownership — konfiguriert granulare Dokumentberechtigungen (none, limited, observer, owner).

• get_users / set_user_role — listet verbundene Benutzer und ändert Berechtigungsrollen mit Schutz vor Selbst-Herabstufung.

• create_journal_entry / get_journal / search_journals / delete_journal_entry — verwaltet Sitzungsnotizen und Überlieferungen.

7. Szene, Wetter & Erkundung

• create_scene / delete_scene / get_scene_info / switch_scene — Szenenerstellung und Spieleraktivierung.

• set_scene_weather — setzt oder entfernt Wettereffekte (rain, snow, fog, "").

• set_scene_lighting — Umgebungsdunkelheit und globale Beleuchtungseinstellungen.

• reset_fog — setzt die Nebel-des-Krieges-Erkundung auf aktiven Szenen zurück.

8. Spielmechanik & Brückenwerkzeuge

• roll_dice — lokale mathematische Würfelformel-Auswertung.

• roll_and_post — wertet Formeln über Foundrys native Engine aus und postet interaktive Chat-Karten.

• lookup_rule — durchsucht Welt-Journale und System-Kompendium-Pakete nach Regeln mit Vorschau-Ausschnitten.

• get_document_schema — untersucht DataModel-Schemata des Spielsystems für Akteur- und Gegenstandstypen.

• search_compendium_content — tiefe Suche in Kompendium-Paketdokumenten und Journalseiten.

• send_chat_message / get_chat_messages — postet und liest Nachrichten aus dem Foundry-Chatprotokoll.

• generate_npc / generate_loot — sofortige prozedurale Generatoren.

9. Diagnose & Protokollierung

• get_health_status / get_system_health — Verbindungs- und Server-Health-Metriken.

• get_recent_logs / search_logs — prüft Serverprotokolle und Fehler-Stacktraces.

• diagnose_errors — analysiert aktuelle Fehler in priorisierte Lösungsvorschläge.

• refresh_world_data — erzwingt ein erneutes Abrufen des gecachten Weltzustands-Snapshots.

🧪 Entwicklung & Testen

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run complete unit test suite (713 tests)
npm test

# Run linter and formatting checks
npm run lint

# Start server in development watch mode
npm run dev

📄 Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.