Content
# Triston's Bridge Fork
**Run your Foundry VTT game from a conversation with Claude.** This is an expanded Game-Master
toolset for the Foundry VTT ↔ Claude Desktop bridge — it lets Claude not just _read_ your world but
_run_ it: build encounters, drive the combat tracker, dress scenes, manage NPCs and loot, write
journals, cue music, and more, all in plain language.
> A fork of **[foundry-vtt-mcp](https://github.com/adambdooley/foundry-vtt-mcp)** by **Adam Dooley**
> (MIT), which provides the entire base bridge, installers, and AI map generation. This fork adds
> **40+ new Game-Master tools** on top. Not affiliated with or endorsed by the original author — see
> [Credits](#credits).
- **Foundry VTT v13 / v14** · works with **D&D 5e, SW5e, PF2e, DSA5, Cosmere RPG, WFRP4e** (most tools
are system-agnostic; some are system-aware)
- **Claude Desktop** on a **Pro or Max** plan
- 📖 **Full tool reference:** [`AI-TOOLSET.md`](AI-TOOLSET.md) — drop it into your Claude workspace so
it understands every command.
---
## What you can do
Just talk to Claude; it picks the right tools. A tour by theme:
### 🎭 Narrate & communicate
Post in-character NPC dialogue, out-of-character notes, or emotes to chat · whisper secretly to
specific players · make hidden GM rolls.
> _"Have the innkeeper greet the party in character, then whisper the secret password to the rogue."_
### ⚔️ Run combat
Drop enemy tokens onto the scene · start the tracker, roll initiative, advance turns · apply
damage/healing · add active effects (buffs, debuffs, conditions) · make NPCs roll saves/skills/attacks
· short & long rests.
> _"Place three guards by the door, start combat, and roll everyone's initiative."_
### 🗺️ Build & dress scenes
Create or switch scenes · generate AI battlemaps (optional ComfyUI backend) · add walls, lights,
tiles, spell/effect templates, map notes, and drawings.
> _"Add flickering torchlight along the left wall and a secret door at the back."_
### 📚 Manage content & lore
Author and **edit** multi-page journals · quests linked to NPCs · roll tables · folders to stay
organized · build reusable **compendium packs** (a bestiary, a loot library) from your world content.
> _"Write a players-visible journal describing the ruined temple, filed under Locations."_
### 🧑🤝🧑 Characters & loot
Query stats, inventory, and abilities · create NPCs from prompts or compendiums · move items between
characters · adjust currency · award XP · duplicate mooks · manage token ownership.
> _"Give the healing potion from the cleric to the fighter and award the party 300 XP."_
### 🎵 Ambiance & rolls
Play/stop playlists and set volume · request dice rolls from players.
> _"Play the tavern music and ask everyone for a Perception check."_
### 🧹 Housekeeping (safe by design)
Confirmation-guarded deletes for actors, items, journals (and single pages), scenes, roll tables,
compendium packs, and scene objects like stray lights/walls.
**Safety model:** every world-changing tool is **GM-only**. The bridge works strictly _inside_ your
active world — it **never creates, overwrites, or deletes the World itself**, and world/system
configuration is **read-only**. Destructive tools require an explicit `confirm`. Running macros
(arbitrary code) is **off** unless you enable it in settings.
👉 See [`AI-TOOLSET.md`](AI-TOOLSET.md) for the complete, categorized tool list.
---
## Installation
The bridge is **two halves that must both be installed and kept in sync**:
1. the **Foundry module** (runs inside Foundry VTT), and
2. the **MCP server** (a small Node process that Claude Desktop launches).
Grab **`foundry-mcp-bridge.zip`** (module) and **`foundry-mcp-server.zip`** (server) from the
[**latest release**](https://github.com/triston-dev/tristons-bridge-fork/releases/latest).
### Requirements
- Foundry VTT **v13 or v14**
- **Claude Desktop** on a **Claude Pro or Max** plan (MCP servers require a paid plan)
- **Node.js 18+** (unless you use the bundled-runtime base installer in Path B)
- Windows 10/11 for the automated base installer; other OSes via source (Path C)
- _(Optional)_ a CUDA GPU with ≥ 8 GB VRAM for AI map generation
### Path A — You already run the original bridge (or an earlier fork build)
Just overlay the two zips:
1. **Module:** replace `Data/modules/foundry-mcp-bridge/` in your Foundry user data with the
`foundry-mcp-bridge/` folder from `foundry-mcp-bridge.zip`.
2. **Server:** fully quit Claude Desktop, then replace the `foundry-mcp-server/` folder inside your
`FoundryMCPServer` install (Windows: `%LOCALAPPDATA%\FoundryMCPServer\`) with the one from
`foundry-mcp-server.zip`. _(Minimal alternative: replace only
`foundry-mcp-server\packages\mcp-server\dist\backend.bundle.cjs`.)_
3. Restart Claude Desktop and reload your world.
### Path B — New install, easiest (Windows: bundled Node + optional ComfyUI)
1. Install the base with the original project's
[**Windows/Mac installer**](https://github.com/adambdooley/foundry-vtt-mcp/releases) — it bundles
the Node runtime, configures Claude Desktop, and optionally sets up ComfyUI map generation.
2. Then apply this fork's two zips exactly as in **Path A**.
### Path C — From source (any OS, self-contained)
```bash
git clone https://github.com/triston-dev/tristons-bridge-fork.git
cd tristons-bridge-fork
npm install
npm run build:release
```
- **Module:** install `foundry-mcp-bridge.zip` into `Data/modules/` (or copy the built
`packages/foundry-module` there as `foundry-mcp-bridge/`).
- **Claude Desktop:** add the server to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"foundry-mcp": {
"command": "node",
"args": ["ABSOLUTE/PATH/TO/tristons-bridge-fork/packages/mcp-server/dist/index.js"],
"env": { "FOUNDRY_HOST": "localhost", "FOUNDRY_PORT": "31415" }
}
}
}
```
Config lives at `%APPDATA%\Claude\claude_desktop_config.json`. **Microsoft-Store** Claude installs use
`%LOCALAPPDATA%\Packages\<…Claude…>\LocalCache\Roaming\Claude\claude_desktop_config.json`.
### Finish (all paths)
1. Start Claude Desktop, then launch Foundry and load your world **as GM**.
2. In Foundry: **Manage Modules → enable "Triston's Bridge Fork."**
3. Its settings should read **Connected**. Ask Claude _"What's the current scene in Foundry?"_ to confirm.
> ⚠️ **Don't rename the module id or its folder.** The MCP server routes to the module by the id
> `foundry-mcp-bridge`; renaming it breaks the connection.
---
## Settings (Foundry → Module Settings → Triston's Bridge Fork)
- **Enable MCP Bridge** — master on/off for the connection (leave on; shows Connected status).
- **Connection Type** — _Auto_ (recommended), _WebRTC_ (internet / remote worlds), or _WebSocket_ (local).
- **Allow Write Operations** — off = Claude can only _read_; on = it can modify world content.
- **Allow Macro Execution** — **off by default**; enables the `execute-macro` tool, which runs
arbitrary code. Leave off unless you trust the connected AI.
- **Max Actors Per Request** — failsafe cap on mass actor creation.
- Reconnect / notification options, plus the **Enhanced Creature Index** and **Map Generation** sub-menus.
## Architecture
```
Claude Desktop ↔ MCP ↔ MCP Server ↔ WebSocket / WebRTC ↔ Foundry Module ↔ Foundry VTT
↓
ComfyUI (optional AI map generation)
```
- **Foundry module** — secure, GM-gated data access inside Foundry VTT.
- **MCP server** — a Node process Claude Desktop launches; talks to the module.
- **No API keys** — uses your existing Claude Desktop subscription.
- **Remote play** — WebRTC lets the server reach a Foundry world hosted elsewhere.
## Building & contributing
```bash
npm install
npm run build:release # builds shared + server bundle + Foundry module
npm run typecheck
```
This repo's remotes: `origin` → this fork, `upstream` →
[adambdooley/foundry-vtt-mcp](https://github.com/adambdooley/foundry-vtt-mcp) (so you can pull upstream
updates). Issues and PRs welcome.
## Credits
- **Original project:** [foundry-vtt-mcp](https://github.com/adambdooley/foundry-vtt-mcp) by
**Adam Dooley** — the base bridge, Windows/Mac installers, and ComfyUI map generation. © 2025 Adam
Dooley, MIT.
- **This fork:** the expanded Game-Master toolset, by
[**triston-dev**](https://github.com/triston-dev). See [`NOTICE.md`](NOTICE.md) for exactly what's added.
- Not affiliated with or endorsed by the original author.
## License
MIT — see [`LICENSE`](LICENSE) (original copyright retained in full). Bundled components used by the
optional installers/map generation (e.g. the D&D Battlemaps SDXL model, 7-Zip) carry their own license
terms; see the installer notices.
