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