Home

Foundry API Bridge

Foundry VTT module for foundry-mcp.com. Connects Foundry VTT to AI assistants (Claude, ChatGPT, etc.) via the MCP protocol over WebSocket. GM-only — the module activates only for the Game Master.

Installation

Method 1: Manifest URL (Recommended)

1. In Foundry VTT, go to Add-on Modules
2. Click Install Module
3. Paste manifest URL:

   https://raw.githubusercontent.com/alexivenkov/foundry-api-bridge-module/master/dist/module.json
   

4. Click Install
5. Enable the module in your world

Method 2: Manual Installation

1. Download latest release from GitHub Releases
2. Extract to Data/modules/foundry-api-bridge/
3. Restart Foundry VTT
4. Enable the module in your world

Setup

1. Get your API key at foundry-mcp.com/auth/patreon
2. Open your world as GM
3. Go to Game Settings → Module Settings → Foundry API Bridge
4. Configure:

Setting	Description	Default
MCP WebSocket URL	WebSocket endpoint for the MCP server (Claude / AI assistant integrations)	wss://foundry-mcp.com/ws
API WebSocket URL	WebSocket endpoint for the public Foundry API (third-party integrations: bots, dashboards, Discord, mobile apps)	wss://api.foundry-mcp.com/v1/connect
API Key	Your personal API key from foundry-mcp.com (validates both connections)	—

The module opens both WebSocket connections in parallel and independently. Failure of one channel has no effect on the other. The same API key authorizes both.

Compatibility

• Foundry VTT: v11, v12, v13
• Game Systems: D&D 5e (optimized), others supported

Commands

Category	Commands
Dice & Chat	roll-dice, send-chat-message, get-chat-messages, delete-chat-message, update-chat-message, clear-chat, export-chat
Actor Rolls	roll-ability, roll-skill, roll-save, roll-attack, roll-damage
Actors	get-actors, filter-actors, get-actor, create-actor, create-actor-from-compendium, update-actor, delete-actor
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, use-item, activate-item, 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	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
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, get-compendium-document, import-from-compendium
System Runtime	get-world-time, advance-time, set-world-time, pause-game, resume-game, get-pause-state, notify, pan-canvas, ping-location

Documentation

• WebSocket API — Full command reference with parameters and examples

Links

• foundry-mcp.com — MCP server
• GitHub Issues — Bug reports and feature requests
• Patreon — Support the project