Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Foundry REST API MCP start combat in the current scene"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets MCP clients work with a Foundry VTT world through the FoundryVTT REST API Relay. It is the client-facing component of the ThreeHats ecosystem:
Foundry VTT + REST API Module <-- WebSocket --> REST API Relay <-- HTTPS --> this MCP serverThe MCP server connects to the relay's HTTP(S) API. Do not use the module's ws:// or wss:// relay URL for FOUNDRY_REST_API_BASE_URL.
Component | Role |
Connects a Foundry world to the relay over WebSocket. | |
Exposes the authenticated HTTP API used by this server. | |
Foundry REST API MCP | Exposes supported relay operations as typed |
Use the upstream relay documentation for module pairing, relay deployment, API-key management, and the complete REST API reference.
This project supports the relay's optional clientId and userId request scoping. A scoped API key can bind either value so the MCP client does not need to provide it. A key scoped to one world therefore does not require FOUNDRY_CLIENT_ID.
Related MCP server: FoundryMCP
Install and pair the Foundry module with either the public relay or your self-hosted relay.
Create an API key in the relay with only the scopes needed for the tools you intend to use.
Add this server to Codex in ~/.codex/config.toml:
[mcp_servers.foundry]
command = "npx"
args = [
"--yes",
"github:zagushka/foundry-rest-api-mcp#v0.5.0"
]
[mcp_servers.foundry.env]
# Public relay:
FOUNDRY_REST_API_BASE_URL = "https://foundryrestapi.com"
FOUNDRY_REST_API_KEY = "replace-with-a-scoped-secret"
# Optional: omit when the key is already scoped to exactly one world.
# FOUNDRY_CLIENT_ID = "fvtt_..."Restart Codex after changing the configuration. Codex starts this stdio server automatically; it does not expose its own HTTP port.
Use the HTTP API address of your relay instead of its WebSocket address. The standard local relay API listens on port 3011:
[mcp_servers.foundry.env]
FOUNDRY_REST_API_BASE_URL = "http://localhost:3011"
FOUNDRY_REST_API_KEY = "replace-with-a-scoped-secret"
# FOUNDRY_CLIENT_ID = "fvtt_..."If Codex should inherit variables already available in its environment, use env_vars instead:
[mcp_servers.foundry]
command = "npx"
args = [
"--yes",
"github:zagushka/foundry-rest-api-mcp#v0.5.0"
]
env_vars = [
"FOUNDRY_REST_API_BASE_URL",
"FOUNDRY_REST_API_KEY",
"FOUNDRY_CLIENT_ID"
]The Git tag pins the installed release. Change it deliberately when upgrading.
All exposed tools begin with foundry_ and publish typed MCP parameters. Request the smallest set of relay scopes needed for the tools you enable:
Tool group | Capabilities | Relay scopes |
World content and folders | Inspect connected worlds; inspect, search, create, update, and delete entities and folders |
|
Users | List users, create an isolated bot/service user |
|
Actor inventory and effects | Add, update, and delete embedded |
|
Files | Browse file sources, download files, and upload base64-encoded files |
|
Scenes and canvas | Manage scenes, canvas documents, token movement, selection, and distance measurement |
|
Encounters and effects | Read and manage combats, combatants, turns, and active effects |
|
Table play | Roll dice and read, send, or delete chat messages |
|
Read-only tools advertise readOnlyHint: true. Tools that change world state advertise readOnlyHint: false; deletion tools and chat clearing also advertise destructiveHint: true. Treat a key that grants write scopes as a privileged credential and keep it outside Git.
Use foundry_create_actor_embedded_documents, foundry_update_actor_embedded_documents, and foundry_delete_actor_embedded_documents to manage one actor's embedded Item or ActiveEffect documents. Pass the actor UUID (for example, Actor.abc123) and an array of document data or IDs. Updates require each document's _id or id.
The relay exposes no dedicated Actor.createEmbeddedDocuments route. For items, the create tool uses its supported actor items upsert; for effects, it uses the relay's effect endpoint. Updating and deleting target the embedded document UUIDs directly.
Use foundry_list_users to find the Foundry user ID for FOUNDRY_BOT_USER_ID; the relay resolves clientId automatically when the API key is locked to one world. foundry_create_user is available only to a GM key with user:write; it accepts no password and returns only a safe subset of user fields.
Use foundry_get_current_client (or foundry_list_clients for more than one connected world) to diagnose the resolved clientId, world ID/title, Foundry version, and connection status without setting FOUNDRY_CLIENT_ID manually.
For every bot reply use foundry_send_chat_as_user, not the generic chat tool. It sends the requested userId to the relay and rejects a response whose ChatMessage.author.id differs. The relay is the authorization boundary: a scoped API key forcibly replaces userId, so callers cannot impersonate another user; an unscoped GM key may choose an author.
For a private reply, pass chatType: 3 and whisper: [originatingPlayerUserId]. The optional live test verifies the complete flow, including invisibility to an unrelated player:
FOUNDRY_REST_API_BASE_URL=https://relay.example \
FOUNDRY_BOT_API_KEY=... FOUNDRY_PLAYER_API_KEY=... FOUNDRY_OTHER_PLAYER_API_KEY=... \
FOUNDRY_BOT_USER_ID=... FOUNDRY_PLAYER_USER_ID=... \
npm run test:private-bot-replyIt intentionally creates two Whisper messages and does not remove them. Use test-world scoped keys with chat:write for the bot/player and chat:read for the unrelated-player visibility check.
The server deliberately does not expose D&D5e-specific operations, sessions, macros, playlists, arbitrary JavaScript, relay authentication management, or SSE/WebSocket subscriptions. Use the upstream API directly when one of those capabilities is required.
git clone https://github.com/zagushka/foundry-rest-api-mcp.git
cd foundry-rest-api-mcp
npm ci
npm testFor a manual local run, copy .env.example to .env, fill in the relay address and API key, then run:
npm run build
npm run start:envMIT © Peter Pshenichny
Add a status or custom active effect.
Inputs: uuid (required), userId, clientId, statusId, +1 more.
Add selected or named tokens to an encounter.
Inputs: uuids, userId, clientId, selected, +2 more.
Permanently clear all chat messages.
Inputs: userId, clientId.
Add Items or ActiveEffects to one actor. Item creation uses the relay's supported Actor items upsert.
Inputs: actorUuid (required), documents (required), documentType (required), userId, +1 more.
Create one or more canvas embedded documents.
Inputs: data (required), documentType (required), userId, sceneId, +1 more.
Create a Foundry world entity.
Inputs: data (required), entityType (required), folder, keepId, +3 more.
Create a Foundry folder.
Inputs: name (required), folderType (required), userId, clientId, +1 more.
Create a new scene.
Inputs: data (required), userId, clientId.
Create a Foundry service or bot user. Requires relay scope user:write and GM access. The tool never accepts, returns, or logs a password.
Inputs: name (required), role (required), color, active, +2 more.
Delete Items or ActiveEffects embedded in one actor.
Inputs: actorUuid (required), documentIds (required), documentType (required), userId, +1 more.
Delete one canvas embedded document.
Inputs: documentId (required), documentType (required), userId, sceneId, +1 more.
Delete one chat message.
Inputs: messageId (required), userId, clientId.
Delete a Foundry entity by UUID or the current selection.
Inputs: uuid, userId, clientId, selected.
Delete a Foundry folder; deleteAll also deletes its contents.
Inputs: folderId (required), userId, clientId, deleteAll.
Delete a scene by ID or name.
Inputs: name, userId, sceneId, clientId.
Download a file from a Foundry file source.
Inputs: path (required), format, source, userId, +1 more.
End an encounter.
Inputs: userId, clientId, encounter.
Get canvas embedded documents from a scene.
Inputs: documentType (required), userId, sceneId, clientId, +1 more.
Get the relay's currently resolved Foundry world. With a scoped key this identifies its clientId without FOUNDRY_CLIENT_ID.
Inputs: no named parameters.
Get active effects on an actor or token.
Inputs: uuid (required), userId, clientId.
Get one Foundry document by UUID, such as Actor.abc123.
Inputs: uuid, actor, userId, clientId, +1 more.
Get a folder and its contents by name.
Inputs: name (required), userId, clientId.
Get the latest roll.
Inputs: userId, clientId.
Get one or more scenes.
Inputs: all, name, active, userId, +3 more.
Get tokens selected in the Foundry client.
Inputs: userId, clientId.
Read folders and document references from a Foundry world.
Inputs: path, types, userId, clientId, +3 more.
Get chat messages with optional pagination and filters.
Inputs: limit, offset, userId, speaker, +2 more.
List Foundry VTT worlds connected to the relay, including their connection status and Foundry version.
Inputs: no named parameters.
List active encounters.
Inputs: userId, clientId.
List files and directories in a Foundry file source.
Inputs: path, source, userId, clientId, +1 more.
Get recent rolls.
Inputs: limit, userId, clientId.
List status effects supported by the game system.
Inputs: userId, clientId.
List Foundry users as id, name, role, isGM, active, and avatar. Requires relay scope user:read and GM access; clientId is auto-resolved for a scoped key.
Inputs: clientId.
Measure distance between two points or tokens.
Inputs: userId, originX, originY, sceneId, +7 more.
Move a token to canvas coordinates.
Inputs: x (required), y (required), name, uuid, +5 more.
Advance to the next encounter round.
Inputs: userId, clientId, encounter.
Advance to the next encounter turn.
Inputs: userId, clientId, encounter.
Return to the previous encounter round.
Inputs: userId, clientId, encounter.
Return to the previous encounter turn.
Inputs: userId, clientId, encounter.
Remove an active effect by ID or status.
Inputs: uuid (required), userId, clientId, effectId, +1 more.
Remove selected or named tokens from an encounter.
Inputs: uuids, userId, clientId, selected, +1 more.
Roll a dice formula.
Inputs: formula (required), flavor, userId, speaker, +3 more.
Search world entities and compendiums.
Inputs: limit, query, filter, userId, +4 more.
Select tokens in the Foundry client.
Inputs: all, data, name, uuids, +3 more.
Create a chat message as a Foundry user and verify the returned ChatMessage.author.id. The relay permits this only for the API key's scoped user, or for a GM key; scoped keys cannot be overridden.
Inputs: userId (required), content (required), alias, speaker, +3 more.
Create a chat message.
Inputs: content (required), alias, flavor, userId, +4 more.
Start an encounter.
Inputs: name, tokens, userId, rollAll, +4 more.
Switch the player-facing active scene.
Inputs: name, userId, sceneId, clientId.
Update Items or ActiveEffects embedded in one actor.
Inputs: actorUuid (required), documents (required), documentType (required), userId, +1 more.
Update one canvas embedded document.
Inputs: data (required), documentId (required), documentType (required), userId, +2 more.
Update a Foundry entity by UUID or the current selection.
Inputs: data (required), uuid, actor, userId, +2 more.
Update a scene by ID, name, or active status.
Inputs: data (required), name, active, userId, +2 more.
Upload a base64-encoded file or data URL to a Foundry file source.
Inputs: fileData (required), filename (required), path, source, +4 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 53 tools
Each tool targets a distinct resource and action, following a clear verb_noun pattern. Even with 53 tools, descriptions are specific enough to avoid confusion between similar-sounding operations like get_folder vs get_structure or get_entity vs search.
All tools share the 'foundry_' prefix and use a consistent verb_noun structure. Minor inconsistencies exist, such as create_canvas_documents (plural) versus update_canvas_document (singular) and send_chat_as_user versus send_chat_message, but these do not undermine overall predictability.
With 53 tools, the server is well beyond the typical well-scoped range of 3-15. While the Foundry domain is broad, the excessive number of tools could overwhelm agents and makes navigation harder. Some tools, like the multiple encounter turn/round controls, could be consolidated.
The tool set covers many core Foundry operations, including entities, scenes, tokens, encounters, effects, rolls, and chat. However, there are notable gaps: users can be listed and created but not updated or deleted, encounters can be started/ended but not created or deleted, and folders have no update operation. These missing lifecycle operations limit full workflow coverage.
Connect any AI to your Foundry VTT world: actors, combat, dice, journals, tokens, compendiums.
Your tabletop campaign's journal, wiki, map, character sheets and combat tracker.
Characters, campaigns, adventures & worlds for D&D 5e/5.5e, Pathfinder, Savage Worlds, Fate, & more.
Read and edit a tabletop campaign's notes, characters, initiative and skills in Arcane Core.
