Foundry API Bridge (Foundry MCP)

Connect your Foundry VTT world to AI assistants (Claude, ChatGPT, Cursor, Gemini, etc.) via foundry-mcp.com. The module syncs world data to the Foundry MCP server and receives commands through WebSocket — enabling AI to read your campaign, roll dice, manage combat, create content, and control tokens through the Model Context Protocol.

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  FULL COMMAND REFERENCE (71 commands)
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

World
   - get-world-info — world overview: game system, content counts, compendium list
   - roll-dice — roll arbitrary dice formulas (1d20+5, 4d6kh3, etc.)

  Scenes
   - list-scenes — all scenes with id, name, active status, background
   - get-scene — full scene details: tokens, walls, lights, notes (optionally with canvas screenshot)
   - activate-scene — switch the active scene for all players

  Actors
   - list-actors — list all actors in the world with IDs
   - search-actors — find actors by name (substring, case-insensitive)
   - get-actor — full actor details: HP, AC, abilities, skills, inventory
   - create-actor — create a new actor from scratch
   - create-actor-from-compendium — spawn monster or NPC from a compendium
   - update-actor — modify HP, XP, name, image, or system data
   - delete-actor — remove actor from the world

  Items
   - get-actor-items — list items in actor's inventory (filter by type, equipped, etc.)
   - use-item — trigger item.use() for potions, spells, weapons
   - activate-item — activate with full Foundry automation (Midi-QOL compatible)
   - add-item-to-actor — create a new item from scratch in inventory
   - add-item-from-compendium — add official item from compendium
   - update-actor-item — modify an item in inventory
   - delete-actor-item — remove item permanently

  Active Effects
   - get-actor-effects — list all effects on actor (conditions, buffs, debuffs)
   - toggle-actor-status — apply or remove a status condition
   - add-actor-effect — create a custom active effect
   - remove-actor-effect — delete an effect
   - update-actor-effect — modify name, icon, disabled state, or changes

  Journals
   - list-journal-folders — journal folders with entry counts
   - list-journals — journal entries (optionally filtered by folder)
   - search-journals — search journals by name across all folders
   - get-journal — journal with all pages (plain text or HTML)
   - get-journal-page — single page by ID
   - create-journal — new journal entry, optionally with initial content
   - update-journal — rename or move a journal
   - delete-journal — remove journal and all pages
   - create-journal-page — add a new page
   - update-journal-page — edit page content
   - delete-journal-page — remove a page

  Combat
   - get-combat — current state: combatants, round, turn, whose turn
   - create-combat — new combat encounter (first step)
   - start-combat — begin round 1 after adding combatants and rolling initiative
   - delete-combat — end and remove the encounter
   - next-turn — advance to next combatant (auto-advances round)
   - previous-turn — undo accidental turn advance
   - set-turn — jump to a specific combatant's turn
   - add-combatant — add actor to combat
   - remove-combatant — remove participant
   - roll-initiative — roll for specific combatants
   - roll-all-initiative — roll for everyone at once
   - set-initiative — manually set initiative value
   - set-combatant-defeated — mark defeated (skull icon, skips turn)
   - toggle-combatant-visibility — show or hide from players

  Tokens
   - get-scene-tokens — list tokens on scene with HP, AC, conditions, disposition
   - create-token — place a token on the scene for an actor
   - move-token — move token to new coordinates
   - update-token — change position, visibility, elevation, rotation
   - delete-token — remove token from scene

  Dice Rolling (D&D 5e)
   - roll-skill-check — skill check with proficiency (Stealth, Perception, etc.)
   - roll-saving-throw — saving throw vs spells, traps, effects
   - roll-ability-check — raw ability check (no skill proficiency)
   - roll-attack — attack roll for a weapon or spell
   - roll-damage — damage roll for a weapon or spell

  Roll Tables
   - list-roll-tables — all tables (encounters, loot, weather, NPC traits)
   - get-roll-table — full table details with results, ranges, weights
   - roll-on-table — draw a random result from a table
   - reset-table — reset drawn results (for no-replacement tables)
   - create-roll-table — new table with dice formula and entries
   - update-roll-table — modify table properties
   - delete-roll-table — remove a table

  Compendiums
   - list-compendiums — all available compendium packs
   - browse-compendium — list documents in a pack (monsters, items, spells)
   - get-compendium-document — full statblock or item details
   - get-compendium-document-raw — complete raw JSON data for detailed calculations
   - search-compendiums — search by name across ALL compendiums at once

  Chat
   - send-chat-message — post to Foundry chat log (narration, dialogue, whispers)

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  TECHNICAL
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

   - Real-time bidirectional sync via REST + WebSocket
   - Auto-reconnect with exponential backoff
   - Selective compendium pack sync (configurable per world)
   - Connection status notifications in Foundry UI
   - Compatible with Foundry VTT v11–v13
   - System-agnostic (optimised for D&D 5e — skill/ability/item rolls use 5e mechanics)

  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  SETUP
  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  1. Install the module via manifest URL: https://raw.githubusercontent.com/alexivenkov/foundry-api-bridge-module/master/dist/module.json
  2. Get an API key at foundry-mcp.com/auth/patreon
  3. In module settings, configure:
       WebSocket URL: wss://foundry-mcp.com/ws
       API Key: your pk_... key
  4. Save and reload the world

  See the wiki for usage examples and troubleshooting: https://github.com/alexivenkov/foundry-api-bridge-module/wiki