Repository navigation
Home
Foundry VTT module that connects your world to Foundry MCP, so an AI assistant — Claude, ChatGPT, Codex, Cursor, Gemini or any MCP client — can read your campaign and act in it: roll dice, run combat, write journals, move tokens, import from compendiums. The module runs only on the Game Master's client, keeps one outgoing connection to the server and executes commands inside Foundry with GM permissions. The same module serves the public REST API at api.foundry-mcp.com.
Current version: 8.18.0. Foundry VTT v11–v14 (verified on v14).
- In Foundry VTT: Add-on Modules → Install Module → search for Foundry API Bridge → Install, then enable it in your world.
- Open the module settings, click Get API Key, sign in with Patreon and paste the key back. A free Patreon account is enough.
- Add
https://foundry-mcp.com/mcpto your AI client and sign in with Patreon when it asks.
From Foundry (recommended). Add-on Modules → Install Module → search for Foundry API Bridge → Install. The module is listed on foundryvtt.com and updates through Foundry's normal update check.
By manifest URL. Paste this into the Manifest URL field of the Install Module dialog:
https://raw.githubusercontent.com/alexivenkov/foundry-api-bridge-module/master/dist/module.json
Manually. Download foundry-api-bridge.zip from the latest release, extract it into Data/modules/foundry-api-bridge/, restart Foundry.
Then enable the module in your world: Game Settings → Manage Modules.
Open foundry-mcp.com/auth/patreon, or click Get API Key under the API Key field in the module settings, and sign in with Patreon. You get a key of the form pk_… plus setup instructions for every supported client. The same page shows your key again whenever you come back to it. If you connect an AI client through OAuth first, the key is created for you at that moment.
Game Settings → Configure Settings → Module Settings → Foundry API Bridge:
| Setting | Default | What it does |
|---|---|---|
| MCP WebSocket URL | wss://foundry-mcp.com/ws |
Channel for AI assistants (MCP). Leave as is. |
| API WebSocket URL | wss://api.foundry-mcp.com/v1/connect |
Channel for the public REST API. Leave as is, or clear it if you never use the REST API. |
| API Key | empty | Your pk_… key. Stored in this browser only; enter it again on another computer. Whitespace that came along with the paste is removed on its own; a value that is not a key (no pk_ prefix, wrong characters or length) is refused with a red notification, on save and on load. |
| Allow Script Macros | off | Lets the API create and run script macros: arbitrary JavaScript with GM rights. Keep it off unless you need it and trust every client that holds your key. |
Save. Foundry reloads the world and two notifications confirm the link: [MCP] Connected to server and [API] Connected to server. Both connections are independent: failure of one has no effect on the other, and the same key authorizes both.
After a network drop the module reconnects on its own. The delay doubles from 5 seconds up to a 60-second ceiling, and it keeps trying for as long as the world is open. While connected it pings the server every 25 seconds; an unanswered ping means the connection is dead, and it is re-established without waiting.
Two closes from the server are not network drops and are handled on their own (since 8.15.0). If the server rejects the key (close code 4001), the module stops reconnecting and shows a red notification that stays until dismissed: fix the key in Module Settings (use the Copy button on your key page) and reload the world. If another Foundry client connects with the same key (4002), the server keeps the newer connection and this client waits two minutes before trying again, with a yellow notification saying so. One key serves one GM client at a time; a second browser, device or your host's own GM session needs the first one closed.
The Configure button next to the module in the module list opens the advanced form:
| Setting | Default | Description |
|---|---|---|
| Enable WebSocket | on | Turn the connections on or off without clearing the URLs |
| Reconnect Interval (ms) | 5000 | Base delay between reconnection attempts; doubles each time |
| Max Reconnect Attempts | 0 | Attempts before the module gives up until the next reload; 0 = keep trying |
| Enable Logging | on | Module logging in the browser console (Foundry API Bridge | …) |
| Log Level | info |
debug, info, warn, error
|
The MCP endpoint is https://foundry-mcp.com/mcp (Streamable HTTP). Where the client supports OAuth, add the URL and sign in with Patreon when asked. Where it does not, send Authorization: Bearer pk_… with every request.
| Client | How to connect |
|---|---|
| Claude (web or desktop) | Settings → Connectors → Add custom connector. Name Foundry, URL https://foundry-mcp.com/mcp, leave client ID and secret empty, click Add, then Connect and sign in with Patreon. |
| ChatGPT (Pro / Team / Enterprise) | Settings → turn on Developer Mode. In a chat: + → Developer Mode → Add Sources, paste the URL, choose OAuth, sign in with Patreon. Enable the connector in each new chat. |
| Claude Code |
claude mcp add --transport http foundry https://foundry-mcp.com/mcp, then run /mcp and choose Authenticate. |
| Codex CLI |
codex mcp add foundry --url https://foundry-mcp.com/mcp, then codex mcp login foundry. |
| Cursor |
~/.cursor/mcp.json: { "mcpServers": { "foundry": { "url": "https://foundry-mcp.com/mcp" } } }, then click Needs login in Settings → MCP. |
| VS Code |
.vscode/mcp.json: { "servers": { "foundry": { "type": "http", "url": "https://foundry-mcp.com/mcp" } } }, then sign in when prompted. |
| Gemini CLI |
gemini mcp add --transport http foundry https://foundry-mcp.com/mcp, then /mcp auth foundry. |
| Windsurf, Cline, other clients | API key: endpoint https://foundry-mcp.com/mcp, Streamable HTTP, header Authorization: Bearer pk_…. |
API-key variants for every client and the Claude Desktop mcp-remote fallback are in the README.
A second endpoint, https://foundry-mcp.com/mcp/code, exposes three tools: docs (the index of the typed foundry.* API, 19 domains and 118 methods, with methods above your tier marked 🔒), query (runs a read-only script) and execute (runs a script with the full API). The assistant writes a short TypeScript script and the server runs it in a QuickJS sandbox against your world, returning a trace of every call with the ids it touched. A static check refuses the script before it runs if it calls a method your tier lacks.
Same module, same key; keep /mcp connected as well. Per script: 150 calls, 150 writes, 30 deletes, 60 s wall time, 15 s CPU, 48 KB result. Runs per day: Guest 10, Free 30, Adventurer 100, Dungeon Master unlimited. There are no transactions: a script that fails half-way does not roll back what it already did. Details on foundry-mcp.com/code.
Connect: claude mcp add --transport http foundry-code https://foundry-mcp.com/mcp/code (Claude Code), codex mcp add foundry-code --url https://foundry-mcp.com/mcp/code then codex mcp login foundry-code (Codex CLI), or a Claude custom connector with the same URL.
Access follows your Patreon membership. Counts are wire commands by the lowest tier that unlocks them.
| Tier | Price | Commands | Unlocks |
|---|---|---|---|
| Guest | Patreon account, no membership | 2 |
get-world-info, roll-dice
|
| Free | free Patreon membership | +56 | actors, inventory and world items, folders, active effects, D&D 5e and Pathfinder 2e rolls, chat, initiative |
| Adventurer | €3 / month | +16 | journals, roll tables |
| Dungeon Master | €10 / month | +45 | scenes and doors, tokens, combat, compendiums and import, world time, pause, UI helpers |
A tool above your tier stays visible to the assistant; calling it returns a short message that names the required tier. Tiers are managed on Patreon; a change of membership reaches the server automatically.
- Foundry VTT: v11 (minimum), v12, v13, v14 (verified)
-
Game systems: the core command set is system-agnostic;
dnd5e/*,pf2e/*,swade/*andcoc7/*commands require the respective system (SWADE verified against swade 6.0.4 on v14, Call of Cthulhu 7e against CoC7 8.16 on v12–v14)
189 wire commands. Full reference with parameters, results and examples: WebSocket API.
| Category | Commands |
|---|---|
| Dice & Chat |
roll-dice, send-chat-message, get-chat-messages, delete-chat-message, update-chat-message, clear-chat, export-chat
|
| Actor Rolls (D&D 5e) |
dnd5e/roll-ability, dnd5e/roll-skill, dnd5e/roll-save, dnd5e/roll-attack, dnd5e/roll-damage, dnd5e/roll-perception (bare roll-<name> are legacy aliases) |
| Compendium Search (D&D 5e) |
dnd5e/filter-compendium-actors, dnd5e/filter-compendium-items
|
| Pathfinder 2e (PF2e) |
pf2e/roll-skill, pf2e/roll-save, pf2e/roll-perception, pf2e/set-condition, pf2e/remove-condition, pf2e/get-conditions, pf2e/increase-condition, pf2e/decrease-condition, pf2e/list-strikes, pf2e/roll-strike, pf2e/roll-strike-damage, pf2e/use-consumable, pf2e/cast-spell, pf2e/post-item, pf2e/filter-compendium-actors, pf2e/filter-compendium-items
|
| Savage Worlds (SWADE) |
swade/roll-attribute, swade/roll-skill, swade/roll-attack, swade/roll-damage, swade/apply-damage, swade/soak, swade/bennies, swade/set-status, swade/get-actor-summary, swade/get-action-cards (since 8.16.0; every actor command takes actorId or tokenId) |
| Call of Cthulhu 7e (CoC7) |
coc7/roll-skill, coc7/roll-characteristic, coc7/roll-attribute, coc7/roll-attack, coc7/roll-damage, coc7/apply-damage, coc7/sanity-check, coc7/bout-of-madness, coc7/luck, coc7/set-condition, coc7/get-actor-summary (since 8.17.0; the world's system id is CoC7; every actor command takes actorId or tokenId) |
| Actors |
get-actors, filter-actors, get-actor, create-actor, create-actor-from-compendium, update-actor, delete-actor, dnd5e/apply-damage, dnd5e/apply-healing (bare apply-damage / apply-healing are aliases) |
| Combat |
create-combat, delete-combat, start-combat, end-combat, next-turn, previous-turn, set-turn, add-combatant, remove-combatant, update-combatant, get-combat-state, get-combat-turn-context
|
| Initiative |
roll-initiative, roll-all-initiative, set-initiative
|
| Combatant |
set-combatant-defeated, toggle-combatant-visibility
|
| Tokens |
create-token, delete-token, move-token, update-token, get-scene-tokens, get-token, get-token-by-actor, set-token-target, clear-targets, get-tokens-in-range
|
| Items (on actor) |
get-actor-items, dnd5e/use-item, dnd5e/activate-item (bare use-item / activate-item are legacy aliases), add-item-to-actor, add-item-from-compendium, update-actor-item, delete-actor-item
|
| Items (world) |
get-items, get-item, filter-items, create-item, update-item, delete-item, create-item-from-compendium
|
| Journals |
get-journals, get-journal, create-journal, update-journal, delete-journal, create-journal-page, update-journal-page, delete-journal-page, show-journal
|
| Scenes |
get-scene, get-scenes-list, activate-scene, capture-scene, create-scene, update-scene, delete-scene, clone-scene, view-scene
|
| Walls & Doors |
set-door-state, get-walls, create-wall, update-wall, delete-wall
|
| Notes |
get-notes, create-note, update-note, delete-note
|
| Effects |
get-actor-effects, toggle-actor-status, add-actor-effect, remove-actor-effect, update-actor-effect
|
| Roll Tables |
list-roll-tables, get-roll-table, roll-on-table, reset-table, create-roll-table, update-roll-table, delete-roll-table
|
| Folders |
get-folders, get-folder, create-folder, update-folder, delete-folder
|
| Macros |
get-macros, get-macro, create-macro, update-macro, delete-macro, execute-macro (since 8.18.0 takes args and returns the macro's value as result) |
| Playlists |
get-playlists, get-playlist, play-playlist, stop-playlist, play-sound-in-playlist, stop-sound-in-playlist, play-sound-once, add-sound-to-playlist
|
| World Data |
get-world-info, get-compendiums, get-compendium, get-compendium-index, search-compendium, search-compendiums, search-compendium-pages, get-compendium-document, import-from-compendium, resolve-uuid
|
| System Runtime |
get-world-time, advance-time, set-world-time, pause-game, resume-game, get-pause-state, notify, pan-canvas, ping-location
|
- The module starts only for the Game Master; nothing runs on players' clients and nothing listens on your machine.
- Your world is not stored on the server; commands pass through to your Foundry client and results go straight back. Revoke access by deleting the key.
- The key is stored in your browser (a client-scoped setting since 8.12.1), not in the world, so players cannot read it.
- Commands run with GM permissions. Script macros are blocked unless Allow Script Macros is on.
- Privacy policy · Terms of service
- WebSocket API — full command reference with parameters and examples
- README — setup, client table, code mode, troubleshooting
- Changelog
- Foundry MCP — the server side · Code mode · REST API reference
- MCP Registry · Smithery · Glama
- Package page on foundryvtt.com
- Patreon — support the project
- GitHub Issues — bug reports and feature requests