Foundry REST API MCP

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 server

The 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.

Ecosystem and compatibility

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

Quick start

1. Install and pair the Foundry module with either the public relay or your self-hosted relay.

2. Create an API key in the relay with only the scopes needed for the tools you intend to use.

3. Add this server to Codex in ~/.codex/config.toml:

[mcp_servers.foundry]
command = "npx"
args = [
  "--yes",
  "github:zagushka/foundry-rest-api-mcp#v0.4.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.

Self-hosted relay

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.4.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.

Supported tools and permissions

All exposed tools begin with foundry_ and publish typed MCP parameters. Request the smallest set of relay scopes needed for the tools you enable:

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.

Actor embedded documents

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.

The server deliberately does not expose D&D5e-specific operations, Foundry-user management, sessions, macros, playlists, arbitrary JavaScript, relay authentication management, or SSE/WebSocket subscriptions. Use the upstream API directly when one of those capabilities is required.

Local development

git clone https://github.com/zagushka/foundry-rest-api-mcp.git
cd foundry-rest-api-mcp
npm ci
npm test

For 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:env

License

MIT © Peter Pshenichny