Foundry VTT MCP Bridge

Verbinden Sie Foundry VTT mit Claude Desktop für KI-gestütztes Kampagnenmanagement über das Model Context Protocol (MCP). Derzeit werden Dungeons and Dragons 5. Edition und Pathfinder 2. Edition unterstützt. Die meisten MCP-Tools sind systemunabhängig, aber Tools zur Charaktererstellung und Kompendium-Suche funktionieren nur mit D&D5e und PF2E.

Übersicht

Die Foundry MCP Bridge ermöglicht natürliche KI-Konversationen mit Ihren Foundry VTT-Spieldaten:

• Quest-Erstellung: Erstellen Sie Quests aus Prompts, die das einbeziehen, was in Ihrer Welt und Ihren Journalen existiert

• Charakterverwaltung: Fragen Sie Charakterwerte, Fähigkeiten und Informationen ab

• Kompendium-Suche: Finden Sie Gegenstände, Zauber und Kreaturen mithilfe natürlicher Sprache

• Inhaltserstellung: Generieren Sie Akteure, NPCs und Quest-Journale aus einfachen Prompts

• Szeneninformationen: Greifen Sie auf aktuelle Szenendaten und Weltdetails zu

• Würfel-Koordination: Interaktive Würfelanfragen mit Zielauswahl für Spieler

• Kampagnenmanagement: Verfolgung von mehrteiligen Quests und Kampagnen

• Kartengenerierung: Erstellen Sie Karten aus Prompts und laden Sie diese automatisch mithilfe der optionalen ComfyUI-Komponente in Szenen in Foundry VTT hoch

Dieses Projekt wurde mit Unterstützung von Claude Code erstellt. Wenn Ihnen dieses Projekt gefällt, ziehen Sie in Betracht, es auf Patreon zu unterstützen.

Related MCP server: Coreflux MCP Server

Installation

Voraussetzungen

• Foundry VTT v13

• Claude Desktop mit MCP-Unterstützung

• Windows (für automatisierten Installer) oder Node.js 18+ für manuelle Installation

Option 1: Windows-Installer

Videoanleitung für den Windows-Installer

1. Laden Sie die neueste FoundryMCPServer-Setup-vx.x.x.exe von Releases herunter

2. Führen Sie den Installer aus - er wird:

   • Den MCP-Server mit gebündelter Node.js-Laufzeitumgebung installieren

   • Die MCP-Server-Einstellungen von Claude Desktop konfigurieren

   • Optional das Foundry-Modul und die ComfyUI-Kartengenerierung in Ihrer VTT-Installation installieren

   • Während der Installation die Cuda-Version für Ihren GPU-Typ auswählen

3. Starten Sie Claude Desktop neu

4. Aktivieren Sie "Foundry MCP Bridge" in Ihrer Foundry-Modulverwaltung

Option 2: Mac-Installer

1. Laden Sie die neueste FoundryMCPServer-vx.x.x.dmg von Releases herunter

2. Führen Sie den Paket-Installer innerhalb der DMG aus - er wird:

   • DMG öffnen und den PKG-Installer per Doppelklick starten

   • Die MCP-Server-Einstellungen von Claude Desktop konfigurieren

   • Optional das Foundry-Modul und die ComfyUI-Kartengenerierung in Ihrer Foundry VTT-Installation installieren

3. Starten Sie Claude Desktop neu

4. Aktivieren Sie "Foundry MCP Bridge" in Ihrer Foundry-Modulverwaltung

Option 3: Manuelle Installation

Installieren Sie das Foundry-Modul

1. Öffnen Sie Foundry VTT v13

2. Wählen Sie im Foundry Add-ons-Menü "Modul installieren"

3. Fügen Sie am unteren Rand des Fensters die Manifest-URL hinzu: https://github.com/adambdooley/foundry-vtt-mcp/blob/master/packages/foundry-module/module.json und klicken Sie auf Installieren

4. Aktivieren Sie "Foundry MCP Bridge" in der Modulverwaltung

   • Ändern Sie nicht die Modul-ID oder den Ordnernamen. Das MCP-Backend und die Claude-Integration erwarten beide, dass sich das Modul in einem Verzeichnis namens foundry-mcp-bridge befindet. Das Umbenennen der ID in module.json unterbricht das Socket-Routing und verhindert, dass Claude das Backend sieht.

Installieren Sie den MCP-Server

# 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

Konfigurieren Sie Claude Desktop

Fügen Sie dies Ihrer Claude Desktop-Konfigurationsdatei (claude_desktop_config.json) hinzu:

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

Das Starten von Claude Desktop startet den MCP-Server.

Erste Schritte

1. Starten Sie Foundry VTT und laden Sie Ihre Welt

2. Öffnen Sie Claude Desktop

3. Chatten Sie mit Claude über Ihre aktuell geladene Foundry-Welt

Beispielanwendung

Sobald die Verbindung hergestellt ist, fragen Sie Claude Desktop:

• "Zeig mir die Werte meines Charakters Clark"

• "Finde alle humanoiden Kreaturen mit HG 12 für eine Begegnung"

• "Erstelle eine Quest über die Untersuchung vermisster Dorfbewohner"

• "Würfle einen Heimlichkeitstest für Tulkas"

• "Was befindet sich in der aktuellen Foundry-Szene?"

• "Erstelle mir eine kleine Karte eines Flussufer-Cottages in Foundry"

Funktionen

• 36 MCP-Tools, die es Claude ermöglichen, mit Foundry zu interagieren

• Charakterverwaltung: Zugriff auf Werte, Fähigkeiten, Inventar und detaillierte Entitätsinformationen

• Token-Manipulation: Bewegen, Aktualisieren, Löschen von Tokens und Verwalten von Statusbedingungen

• Erweiterte Kompendium-Suche: Sofortige Filterung nach HG, Typ, Fähigkeiten und mehr

• Inhaltserstellung: Generieren Sie Akteure, NPCs und Quest-Journale

• Kampagnenmanagement: Mehrteilige Quest-Verfolgung mit Fortschritts-Dashboards

• Interaktives Würfelsystem: Senden Sie verschiedene Würfelanfragen von Claude an Spieler

• Akteursbesitz: Verwalten Sie Spielerberechtigungen für Charaktere und Tokens

• Nur für Spielleiter (GM): Die MCP Bridge verbindet sich nur mit Spielleiter-Benutzern

• Kartengenerierung: Ein portables ComfyUI-Backend, das Schlachtkarten aus Prompts generiert

• Remote-Verbindungen: WebRTC-Verbindungen, die über den Browser initiiert werden (getestet mit Google Chrome) zum MCP-Server und ComfyUI

• Windows- und Mac-Installer: Automatisierte Installation des Foundry MCP-Servers für Claude Desktop, des Foundry VTT-Moduls Foundry MCP Bridge und des ComfyUI-Backends mit Abhängigkeiten

MCP-Tools

• 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

Einstellungen

• Erweiterter Kreaturenindex: Die Schaltfläche "Erweiterter Index" führt zum Untermenü "Erweiterter Kreaturenindex" (Details unten)

• Konfiguration des Kartengenerierungsdienstes: Die Schaltfläche "Kartengenerierung konfigurieren" führt zum Untermenü "Kartengenerierungsdienst" (Details unten)

• MCP Bridge aktivieren: Dies sollte standardmäßig aktiviert sein und der Status sollte als "verbunden" angezeigt werden. Es kann verwendet werden, um die MCP Bridge-Verbindung im Spiel zu deaktivieren, ohne das Add-on selbst deaktivieren zu müssen.

• Verbindungstyp: Kann auf "Auto" für die automatische Erkennung des Verbindungstyps eingestellt werden. Kann auch erzwungen werden, entweder WebRTC für Internetverbindungen oder Websocket für lokale Verbindungen.

• Websocket-Server-Host: IP-Adresse des Standorts des Claude Desktop MCP-Servers. Wird nur für lokale Netzwerk-Websocket-Verbindungen verwendet. Remote-Server verwenden WebRTC. Standardmäßig localhost.

• Schreibvorgänge zulassen: Dies verhindert, dass Claude Änderungen am Welteninhalt vornimmt, und beschränkt es auf reinen Lesezugriff.

• Maximale Akteure pro Anfrage: Dies ist eine Sicherheitsmaßnahme, um zu verhindern, dass eine riesige Menge an Akteuren aus einer einzigen Anfrage erstellt wird. Es begrenzt nicht die Anzahl der Charaktere, die durch mehrere Anfragen erstellt werden.

• Verbindungsnachrichten anzeigen: Dies kann die Banner-Nachrichten für Verbindungen der Foundry MCP Bridge ausschalten.

• Automatische Wiederverbindung bei Verbindungsabbruch: Versucht automatisch, die Verbindung wiederherzustellen, falls sie verloren geht.

• Häufigkeit der Verbindungsprüfung: Wie oft der Verbindungsstatus überprüft wird.

Untermenü "Erweiterter Kreaturenindex"

• Kreaturenindex neu erstellen: Diese Schaltfläche erstellt den Kreaturenindex neu, falls ein Problem vorliegt oder er nicht mit den Änderungen in Ihren Kompendien synchron ist.

• Erweiterten Kreaturenindex aktivieren: Dies sollte aktiviert bleiben, da Claude zusätzliche Metadaten in den Weltdateien erstellt, um bessere Suchergebnisse zu ermöglichen.

• Index bei Pack-Änderungen automatisch neu erstellen: Experimentelle Funktion, die noch nicht vollständig getestet wurde.

Untermenü "Kartengenerierungsdienst"

• Dienststatus: Es gibt drei Schaltflächen für "Status prüfen", "Dienst starten" und "Dienst stoppen". Diese Schaltflächen helfen bei der Überwachung und Steuerung der Verbindung von der Foundry MCP Bridge zum ComfyUI-Backend, das von der Claude Desktop-Anwendung gestartet wird.

• Kartengenerierungsdienst automatisch starten: Steuert, ob die ComfyUI-Dienstverbindung beim Start der Foundry-Welt automatisch hergestellt wird.

• Generierungsqualität: Steuert die Qualität der Karten, die von den SDXL-Checkpoints mit ComfyUI generiert werden. "Niedrig" verwendet 8 Generierungsschritte, "Mittel" verwendet 20 Schritte und "Hoch" verwendet 35 Schritte. Der D&D Battlemaps SDXL Upscale v1.0 Checkpoint, der in dieser Bilderzeugung verwendet wird, empfiehlt die Verwendung von 35 Schritten, aber auf Low-End-GPUs oder GPUs ohne CUDA dauert diese Generierung mehrere Minuten. Diese Optionen bieten einen Kompromiss, um Karten schneller auf Kosten der Qualität zu generieren.

Architektur

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

• Foundry-Modul: Bietet sicheren Datenzugriff innerhalb von Foundry VTT

• MCP-Server: Externer Node.js-Server, der die Kommunikation mit Claude Desktop abwickelt

• Kartengenerierungsdienst: Ein Headless-ComfyUI-Backend, das von Claude Desktop gestartet wird

• Keine API-Schlüssel erforderlich: Nutzt Ihr bestehendes Claude Desktop-Abonnement

Sicherheit & Berechtigungen

• Zugriff nur für Spielleiter (GM): Alle Funktionen auf Spielleiter-Benutzer beschränkt

• Konfigurierbare Berechtigungen: Steuern Sie, auf welche Daten Claude zugreifen und was es ändern kann

• Sitzungsbasierte Authentifizierung: Nutzt das integrierte Authentifizierungssystem von Foundry

Systemanforderungen

• Foundry VTT: Version 13

• Claude Desktop: Neueste Version mit MCP-Unterstützung

• Claude Pro/Max-Plan: Erforderlich für die Verbindung zu MCP-Servern

• Betriebssystem: Windows 10/11 (Installer) oder andere Betriebssysteme/manuelle Windows-Installation mit Node.js 18+ (manuell)

• GPU-Anforderungen: Eine GPU mit mindestens 8 GB VRAM

Schema-Smoke-Test

Der MCP-Schema-Smoke-Test überprüft, ob Tool-Schemas korrekt geladen werden und keine zu strengen additionalProperties-Standardwerte erzwingen.

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

Support & Entwicklung

• Probleme: Melden Sie Fehler unter GitHub Issues

• YouTube-Kanal: Abonnieren Sie für Updates und Tutorials

• Dokumentation: Mit TypeScript erstellt, umfassende Dokumentation enthalten

• Lizenz: MIT-Lizenz (Zusätzliche Lizenzen von Drittanbietern sind für gebündelte Komponenten der Installer enthalten)