Foundry Claude Bridge

A small program that runs on the same computer as Foundry VTT and gives Claude a set of tools inside your world: read and send chat, roll dice, look up actors, scenes, tokens, combat and journals, and drive the Lythara Survey Sheet map module. It keeps its own hidden browser logged into Foundry as a GM user, and exposes the tools to Claude as a custom connector (MCP over HTTPS, OAuth sign-in).

Nothing in it deletes documents, changes settings or installs modules. Running arbitrary scripts is off unless you turn it on in config.json. Every call is written to data/audit.log.

What you need

• Windows PC running Foundry VTT v13 or v14 (the one Foundry already runs on).

• Node.js 20 or newer: https://nodejs.org (LTS installer, defaults are fine).

• A public HTTPS address for the bridge, e.g. a Cloudflare Tunnel route bridge.yourdomain.com → http://localhost:8787. Claude's servers must be able to reach it.

• A GM user in Foundry for the bridge (e.g. Claude Bridge, role Gamemaster). Make it in Foundry's User Management. It should not be a user anyone else logs in with, because Foundry 14 allows one login per user.

Related MCP server: foundry-cli

Install (once)

1. Unzip this folder somewhere permanent, e.g. C:\FoundryBridge.

2. Open Command Prompt in that folder (type cmd in the folder's address bar) and run:

   npm install
   npx playwright install chromium
   npm run setup

   setup asks for: the public address (e.g. https://bridge.yourdomain.com), the local port (8787), Foundry's local address (http://localhost:30000), the bridge's Foundry user, its Foundry password if it has one, and an approval passphrase. The passphrase is what you type in the browser when you add the connector in Claude; it is stored only as a hash.

3. Start it: npm start (or double-click start-bridge.cmd). The window shows joined "<world>" as <user> once it's in. Leave it running; a world restart is handled by itself.

4. In Cloudflare: Networking → Tunnels → your tunnel → Routes → Add route → Published application: subdomain bridge, your domain, service http://localhost:8787.

5. Check https://bridge.yourdomain.com/health in a browser: {"ok":true,"foundry":"ready",...}.

Connect Claude

In claude.ai: Settings → Connectors → Add custom connector → name it (e.g. Foundry) and enter the URL https://bridge.yourdomain.com/mcp. Claude opens the bridge's approval page; type the passphrase and click Approve. That's the only time the passphrase is used. Then turn the connector on in a chat and ask Claude for the Foundry status.

To disconnect Claude later: remove the connector in claude.ai, or stop the bridge, or delete data/tokens.json (every connection must then be approved again).

Start with Windows (optional)

Task Scheduler → Create Basic Task → "Foundry Bridge" → trigger When I log on → action Start a program: C:\FoundryBridge\start-bridge.cmd, start in C:\FoundryBridge. Tick "Run with highest privileges" only if Foundry itself needs it; normally not.

Files

• config.json — your settings (made by npm run setup). allowScripts: true enables the run_script tool.

• data/audit.log — one line per tool call: time, tool, arguments, result.

• data/bridge.log — connection events. data/tokens.json, data/clients.json — Claude's connections.

Tools

foundry_status, chat_read, chat_send, roll, actors_list, actor_get, scenes_list, scene_activate, scene_view, tokens_list, token_move, combat_get, journal_search, journal_get, map_sheet_create, map_sheet_render, map_exploration_sync, map_sheet_export, map_sheet_apply, job_status, and run_script when allowed.

Updating

Replace the files (keep config.json and data/), run npm install, restart the bridge.

Testing without Foundry

npm test runs the bridge against a stub Foundry and checks the OAuth handshake and every tool. It needs Playwright's Chromium (npx playwright install chromium).