Allows importing content from Obsidian vaults into Foundry VTT, with preview and dry-run capabilities.
Click on "Install 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 VTT MCP Server roll a d20 for the rogue's stealth check"
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.
Focused MCP server connecting an MCP-compatible agent to Foundry VTT v14 and D&D 5e.
Hermes → MCP Server (stdio) → Sidecar (REST :30001) → Foundry (Socket.IO :30000)
↕
Same-origin reverse proxy /mcp-bridge ↔ MCP Bridge module (active GM client)The sidecar runs alongside Foundry and handles Socket.IO auth internally. The MCP server talks plain HTTP — no auth handshake, no session cookies, no internal protocol concerns. The optional MCP Bridge module supplies values prepared by Foundry's client runtime, such as derived AC, HP maximum, and spell-slot maxima; it requires an active GM browser session and communicates over a same-origin HTTPS /mcp-bridge long-poll route. It also performs confirmation-guarded direct HP, temporary-HP, condition, and spell-slot changes through the Foundry Actor API.
Auth method: a private API key (X-API-Key header) between Hermes and the sidecar. The GM browser bridge does not use that key.
Related MCP server: Foundry VTT MCP Bridge
This file and AGENTS.md are the entry points; everything else lives in docs/:
Doc | What it's for |
Planned work, by phase | |
Live-deployment inspection data, architectural findings, and current known gaps | |
Developer reference: repo layout, deploy/test workflow | |
Precise contract for an external client (search/read/write journal routes, real response examples, error semantics) — for building outside this repo, not for working inside it | |
Original implementation plan — historical, not current |
tests/ holds both test suites: automated tests (npm test) and natural-language agent-behavior scenarios (tests/scenarios/), with tests/README.md explaining how to run each.
npm install
npm run build
npm start# Configure these environment values in your MCP client.
mcp_servers:
foundryvtt:
command: "node"
args: ["~/.hermes/mcp-servers/foundryvtt/dist/index.js"]
env:
FOUNDRY_URL: "http://foundry-sidecar-host:30001"
FOUNDRY_API_KEY: "<private-sidecar-api-key>"
FOUNDRY_WRITE_ENABLED: "true"
connect_timeout: 30Tool | Description |
| Confirm server availability |
| Actor/scene/item/combat/user counts |
| Foundry/system versions, active modules, and prepared-bridge GM responders |
| Search actors by name + optional type filter |
| Raw, unprepared actor data for debugging; embedded Items are opt-in |
| Concise raw 5e snapshot; derived fields may require Foundry UI confirmation |
| Prepared 5e values from an active GM Foundry client |
| Prepared HP, AC, conditions, and spell slots for all character actors |
| Paginated embedded Item list, filterable by name, type, and 2014/2024 source |
| Paginated embedded Activity list, filterable by Item, name, type, and rules source |
| Discovery-only inspection of one activity's targeting, consumption, rolls, and effects; never executes it |
| Report document shape and rules mix; not a combat-readiness check |
| Search world-level items by name + optional type filter |
| Full world-level Item document |
| All scenes with activation status |
| Tokens on a scene (positions, actors, disposition, vision) |
| Active combat: round, turn, sorted combatants, initiative |
| Recent chat messages, optional speaker filter |
| Search journal entries by name, page content, type, tag, and folder; returns snippets and per-page hits |
| Journal entry with all page content, classified type, and per-page content hashes |
| Journal folders, for filtering |
| Verify the sidecar's journal permission filtering agrees exactly with Foundry's own |
| Non-GM users and the character names they own — stable references for the player-scoped tools below |
| Search the journal strictly as one named player would see it in Foundry; an empty result never implies the subject doesn't exist |
| One journal entry as one named player would see it; unreadable entries and hidden pages report as not found, identically to a nonexistent id |
| Dry-run report of |
| All users with roles and online status |
| Verify sidecar connectivity |
Tool | Description |
| Any formula: |
Tool | Description |
| Calculate direct damage/healing through the GM bridge and return a short-lived confirmation token; does not change Foundry |
| Preview replacing temporary HP with an exact value through the GM bridge and return a short-lived confirmation token; does not change Foundry |
| Preview adding or removing one standard condition through the GM bridge; exhaustion is intentionally excluded |
| Preview exact spell-slot values through the GM bridge; returns a short-lived confirmation token. Administrative counter adjustment — does not cast spells. Supports pact magic, character actors only |
| Read-only eligibility check for one exact, unambiguous embedded dnd5e utility activity with no external target; returns a short-lived confirmation token |
| Preview creating a journal entry, or adding/updating one page, with a required, explicit visibility ( |
| Preview linking an actor to a journal entry (not the biography field); reads current link flags from the world snapshot — no GM bridge required |
FOUNDRY_WRITE_ENABLED)Tool | Description |
| Execute exactly one previewed dnd5e utility activity through the GM bridge; dnd5e controls consumption, effects, and chat output |
| Replace an actor's temporary HP with a previewed exact value through the GM bridge; use 0 to clear it |
| Apply an exactly matching, previewed direct HP damage/healing change through dnd5e's |
| Apply an exactly matching, previewed spell-slot adjustment through the GM bridge. Stale-state protected — rejects if slots changed since preview |
| Apply an exactly previewed standard-condition change through the GM bridge |
| Apply an exactly previewed journal write through the GM bridge; the receipt names every player who can see the result, read back from the written document |
| Apply an exactly previewed actor-journal link through the GM bridge; sets bidirectional flags on both documents and reads them back as the receipt |
| Patch actor system attributes ( |
| Create a minimal actor; use Plutonium for complete 5e characters and creatures |
| Delete an actor by ID |
| Advance combat through the sidecar's current internal combat operation |
| Post to Foundry chat |
The sidecar is a small Node.js Express server that runs in Docker alongside Foundry. It:
Authenticates with Foundry via the proven 4-step Socket.IO flow (using extraHeaders: {Cookie} — not query: {session}, which Foundry v14 rejects)
Exposes REST endpoints that proxy to Foundry's Socket.IO protocol
Auto-restarts on failure (Docker restart: unless-stopped)
Deployment components:
sidecar/ — Dockerized sidecar server
module/ — active-GM prepared-data bridge module
traefik/foundry-mcp-bridge.yml — an optional Traefik example for the same-origin bridge route
Any reverse proxy may be used. It must route the Foundry origin's /mcp-bridge path to the sidecar while preserving the browser's Foundry session cookie.
Environment:
FOUNDRY_URL=http://foundry:30000 # Docker service name
FOUNDRY_USERNAME=<foundry-service-account-name>
FOUNDRY_PASSWORD=<private-foundry-account-password>
PORT=30001
API_KEY=<private-sidecar-api-key>
FOUNDRY_WRITE_ENABLED=true # Must be set here as well as in the MCP client to enable mutations
PLAYER_API_KEY=<private-player-scoped-api-key> # Optional. Reaches only /api/mcp/players/* — never GM routes, never writesMethod | Path | Description |
GET |
| Health check |
POST |
| Verify and refresh the current world snapshot |
GET |
| Cheap publish preflight for an external client — writeEnabled, Foundry connectivity, and GM-bridge availability, with no outbound call to Foundry |
GET |
| Counts |
GET |
| Foundry/system metadata, active modules, and prepared-bridge responders |
GET |
| Search actors |
GET |
| Raw actor without embedded Items by default ( |
GET |
| Concise D&D 5e actor summary |
GET |
| Prepared D&D 5e actor summary; requires an active GM client with the bridge module |
GET |
| Prepared concise overview of all character actors; requires an active GM client |
POST |
| Read-only direct HP damage/healing preview; returns one-time confirmation token |
POST |
| Apply an exactly matching, previewed direct HP change through the active GM client |
POST |
| Read-only exact temporary-HP replacement preview; returns one-time confirmation token |
POST |
| Apply an exactly matching, previewed temporary-HP replacement through the active GM client |
POST |
| Read-only standard-condition change preview; returns one-time confirmation token |
POST |
| Apply an exactly matching, previewed standard-condition change through the active GM client |
POST |
| Read-only exact spell-slot adjustment preview; returns one-time confirmation token; character actors only |
POST |
| Apply an exactly matching, previewed spell-slot adjustment through the active GM client; stale-state protected |
POST |
| Validate one exact unambiguous dnd5e utility activity and issue a one-time confirmation token |
POST |
| Execute an exactly matching previewed dnd5e utility activity through the active GM client |
POST |
| Read-only actor-journal link preview; reads current link flags from the world snapshot (no GM bridge needed); issues a one-time confirmation token |
POST |
| Apply an exactly matching, previewed actor-journal link through the active GM client; sets bidirectional flags on both documents |
GET |
| Paginated embedded Item list |
GET |
| Paginated embedded Activity list |
GET |
| Concise discovery-only detail for one embedded Activity |
GET |
| 5e actor validation report |
POST |
| Create a minimal actor |
POST |
| Update actor system |
POST |
| Delete an actor |
GET |
| Search items |
GET |
| One item |
GET |
| All scenes |
GET |
| Scene tokens |
GET |
| Active combat |
POST |
| Advance turn |
GET |
| Chat messages |
POST |
| Post message |
GET |
| Search journal (name, page content, type, tag, folder); each result includes a |
GET |
| One entry, all pages, with content hashes and per-page |
GET |
| Journal folder tree |
POST |
| Diff the sidecar's permission computation against Foundry's own |
POST |
| Read-only journal write preview; resolves |
POST |
| Apply an exactly matching, previewed journal write (create entry / add page / update page) through the active GM client; requires |
GET |
| Non-GM users and the character names they own — accepts |
GET |
| Every journal page visible to at least one non-GM user, with a content hash and its visible-user-id set; full enumeration, not a delta feed — accepts |
GET |
| Journal search filtered to exactly what |
GET |
| One entry as |
GET |
| All users |
/mcp-bridge is an internal browser-to-sidecar transport, not a general MCP API. A GM browser pairs by presenting its existing Foundry session cookie; the sidecar validates that session and issues an in-memory, per-client token that expires when the bridge goes idle. No shared API key is shipped in the module. The separate sidecar API key must be supplied privately through environment configuration and must never be committed.
scripts/import-obsidian.mjs migrates an Obsidian vault into Foundry journal entries, driving the same gated preview/write routes as preview_journal_write/apply_journal_write — there is no second write mechanism.
Everything defaults to GM-only. A note becomes player-visible only if its frontmatter explicitly requests it and the command line opts into that profile — the note is downgraded, never upgraded, on any ambiguity:
---
type: person # -> knowledge.type
tags: [noble, ravencroft] # -> knowledge.tags
foundry-visibility: party # gm (default) | party | players
foundry-visibility-players: Alice, Bob # required when foundry-visibility: players
aliases: [Firstname, Lastname] # for wikilink resolution
---A GM-only section — either an Obsidian callout whose type or title matches (> [!warning]- DM Only is the confirmed convention; configurable via --secret-marker) or a heading literally titled to match (e.g. ## DM Notes) — is automatically split into its own GM-only page. This isn't optional: a single Foundry page can't hold two ownership levels.
# Dry run — the default. Nothing is written.
npm run import:obsidian -- /path/to/vault
# Same, machine-readable (also what preview_obsidian_import uses internally)
npm run import:obsidian -- /path/to/vault --json
# Actually write. Requires typing the exact count of newly player-visible
# notes to proceed.
API_KEY=<private-sidecar-api-key> FOUNDRY_SIDECAR_URL=http://foundry-sidecar-host:30001 \
npm run import:obsidian -- /path/to/vault --apply --allow-visibility party,players
# Re-verify a prior import's ownership still matches the manifest
npm run import:obsidian -- /path/to/vault --verifyIdempotent: a <vault-parent>/obsidian-import-manifest.json (never inside this repo) tracks each note's resolved entry/page ids, content hash, and visibility. Unchanged notes are skipped; changed content becomes an update-page; a changed visibility is reported and refused unless --allow-visibility-change is also passed — a visibility change on re-import is exactly the accident that would publish the campaign bible. --limit N and --only <pattern> scope a first run to a handful of notes before running the whole vault. Wikilinks ([[Foo]], [[Foo|bar]]) resolve to @UUID[...] enrichers once their target has been imported; unresolved or ambiguous links are left literal and reported, never guessed.
The preview_obsidian_import MCP tool runs the same dry run and returns the same report conversationally — it has no --apply equivalent and cannot write; applying an import is a human running the script directly.
The deployment scripts copy only the checked-in sidecar and bridge-module files. They back up every replaced remote file with a timestamp, validate Docker Compose, rebuild only foundry-sidecar, and never print credentials. Set the deployment paths for your host first:
export FOUNDRY_DEPLOY_TARGET="user@foundry-host"
export FOUNDRY_COMPOSE_DIR="/path/to/compose-directory"
export FOUNDRY_SIDECAR_DIR="/path/to/sidecar-directory"
export FOUNDRY_MODULE_DIR="/path/to/foundry/Data/modules/foundry-mcp-bridge"
# Optional: copy the included Traefik example. Omit for another reverse proxy.
export FOUNDRY_PROXY_CONFIG_DIR="/path/to/traefik/dynamic-config"# Sidecar health and Foundry connection only; safe before a GM refresh.
npm run deploy:foundry
# After hard-refreshing Foundry in an active GM browser session.
npm run smoke:foundry -- --require-bridge
# Also verify the journal permission model still agrees with Foundry's own
# testUserPermission — worth running after any Foundry/dnd5e upgrade.
npm run smoke:foundry -- --audit-journal-visibilityThe smoke script uses the sidecar container's private API key internally, reports Foundry/system versions plus responder count, and does not mutate world data.
Session cookies must use extraHeaders: {Cookie} — not query: {session}. Foundry v14 rejects query-param sessions (the standard foundryvtt-mcp npm package gets this wrong).
modifyDocument requires broadcast: true and userId fields in the request.
Combat turn is an index into Foundry's computed sort order, not the cached combatants array. The current next_turn endpoint remains an internal update and should be replaced by a rule-aware execution path before stable release.
world and modifyDocument are internal Socket.IO protocols — point releases may alter payloads.
Array fields in document updates are replaced wholesale, not merged.
When Foundry updates:
The sidecar may need auth flow adjustments (isolated in connect())
The MCP server usually needs no changes (it just talks HTTP)
If modifyDocument payload shape changes, update the POST handlers in the sidecar
The bridge module has a Foundry-compatible manifest and can be installed or updated from:
https://github.com/Hybridenishi/foundryvtt-mcp/releases/latest/download/module.json
Create its release asset after validating the build:
npm run package:module
gh release create v1.7.0 release/foundry-mcp-bridge.zip module/module.json \
--title "MCP Bridge v1.7.0" --notes "Prepared party overview, safe standard-condition changes, server-side write gating, typed damage, and spell-slot adjustment."The ZIP contains module.json and scripts/ at its root, as required by Foundry's module installer.
This server cannot be installed
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Manage TTRPG campaigns: NPCs, locations, factions, quests, sessions, lore, and knowledge graphs.
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
Official remote MCP server for Archivist AI TTRPG campaign memory: characters, sessions, and more.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Hybridenishi/foundryvtt-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server