fvtt-mcp-molten5e

A D&D 5e–only, Molten Hosting–optimized Model Context Protocol server for Foundry VTT, driven by Claude Code. It lets an AI assistant read and edit a live Foundry world (actors, items, journals, scenes, compendia, combat…) and manage a Molten-hosted server's lifecycle and files.

This is the tool/engine layer of a larger AI co-DM project. It is a maintained fork of adambdooley/foundry-vtt-mcp ("Foundry MCP Bridge"), stripped to D&D 5e only (ComfyUI map-generation and all non-5e systems removed) and extended with a Molten-Hosting lifecycle/file tool group. It tracks upstream loosely, not commit for commit.

Status: work in progress. Scaffold + dependency hardening + the Molten "Plane B" tool group are done. Wiring into Claude Code and the live end-to-end test against a real Molten world are in progress. See docs/PLAN.md for the roadmap and docs/HANDOFF.md for current state.

---

Why this shape

Managed Foundry hosts (like Molten) don't expose a general control API and you can't run a process next to the game server. So the bridge runs as a Foundry module in the GM's own browser, which connects out to an MCP server on the GM's PC (bound to localhost). Claude Code talks to that local MCP server.

The browser↔localhost hop uses WebRTC (DTLS data channel, localhost-exception HTTP signaling on :31416, Google STUN) rather than a plain WebSocket — this is what lets a page served over HTTPS reach localhost without a mixed-content block or a local TLS cert. It is load-bearing, not bloat.

Claude Code  ──stdio──>  MCP server (your PC, localhost)
                              │  WebRTC data channel (DTLS)
                              ▼
                    Foundry module (GM's browser tab)
                              │  Foundry's own socket
                              ▼
                    Foundry VTT world (Molten-hosted)

Two-plane model

• Plane A — the live bridge. World data (actors, items, journals, scenes, compendia, combat, ownership, dice). Goes through the browser module over the WebRTC bridge while the server is awake.
• Plane B — Molten lifecycle & files. Talks to Molten's own endpoints directly (no bridge): wake a slept server via the Magic URL, watch the sleep-warning socket, keep a session awake, and upload/serve static assets over WebDAV. See docs/DESIGN.md §4.

Safety rule baked in: a running world's database (LevelDB stores under Data/worlds/<world>/data/) must never be written over the file channel — that corrupts it. Plane-B file ops are restricted to static assets; bulk DB edits are an offline-only flow (stop → backup → unpack → edit → pack → start). The Molten management panel is never scripted (their ToU forbids it); only WebDAV, the Foundry server, and the Magic-URL GET are automated.

---

Repository layout

packages/
  mcp-server/      @foundry-mcp/server — the MCP server (Plane A tools + Plane B molten/ group)
  foundry-module/  @foundry-mcp/module — the Foundry browser module (the bridge endpoint)
shared/            @foundry-mcp/shared — types/protocol shared by both
docs/              DESIGN.md, PLAN.md, HANDOFF.md, tool specs
  upstream/        archived original (Adam's) README + docs, for reference
research/          cached Molten Hosting wiki dump + the fetch script
scripts/           dev/maintenance scripts (MCP schema smoke test)

Requirements

• Node.js 18+ (developed on 24). On Windows, if Node isn't on PATH, use the full path to node.exe (see wiring below).
• Foundry VTT 14.x with the D&D 5e system, hosted on Molten (Elite tier assumed for the Plane-B sleep/wake behavior).

Build

npm install
npm run build          # builds shared, server, and module

Individual workspaces: npm run build:shared, npm run build:server, npm run build:foundry. Tests: npm test (server unit tests run on vitest).

Wire into Claude Code

Register the built MCP server in your Claude Code config. Copy .mcp.json.example to a .mcp.json Claude Code reads (project-scoped, or your ~/.claude.json mcpServers) and set absolute paths:

{
  "mcpServers": {
    "foundry-molten5e": {
      "command": "C:/Program Files/nodejs/node.exe",
      "args": ["C:/path/to/fvtt-mcp-molten5e/packages/mcp-server/dist/index.js"]
    }
  }
}

• Use an absolute path to dist/index.js (Claude Code may launch the server from any directory).
• On Windows, point command at the full node.exe path if Node isn't on PATH.
• The server loads its .env from the repo root regardless of working directory.

Then install the @foundry-mcp/module build into your Foundry world and enable the bridge. (The live install + smoke test is the current in-progress step — see docs/PLAN.md Phase 3.)

Configuration

Copy .env.example to .env (gitignored) and fill in your instance:

• Non-secret, per-instance: MOLTEN_SERVER_URL, MOLTEN_WORLD_ID, MOLTEN_WEBDAV_URL, MOLTEN_FILEBROWSER_URL. The committed defaults are neutral your-server/your-world placeholders.
• Secrets (never commit — env only): MOLTEN_MAGIC_KEY (wake-server), MOLTEN_WEBDAV_PASSWORD (upload-asset), MOLTEN_ADMIN_KEY. Read them from your Molten panel → Server Details. Each tool reports which variable to set if its secret is missing.

Tools

38 tools total: 33 Foundry (Plane A) + 5 Molten (Plane B).

Plane A covers world introspection and editing — characters/actors, items & compendium search, journals/quests, scenes, combat/encounters, ownership, dice rolls, and 5e-specific helpers (e.g. NPC creation). Plane B adds:

Tool	What it does
wake-server	GET the Magic URL (?s=<key>) to boot a slept server — the only allowed control automation
sleep-watch	Subscribe to Molten's shutdown-warning socket to learn when sleep is imminent
keep-awake	Generate light activity so the idle timer doesn't sleep the server mid-session
upload-asset	WebDAV PUT a file under Data/ (assets only; refuses live-world DB paths)
asset-url	Map a Data/-relative path to its public HTTPS URL (pure, no network)

asset-url is fully implemented; the other four Plane-B tools are stubs pending the live Molten integration (Phase 3) and return a clearly-labelled [STUB] response describing their endpoint and safety rules.

Credits & license

MIT, inherited from the upstream project. This is a fork of adambdooley/foundry-vtt-mcp by Adam Dooley — the WebRTC bridge architecture and the bulk of the Foundry tool surface are his work. The original project README and docs are preserved under docs/upstream/. See LICENSE.