Atlas VTT MCP Bridge

The agentic companion for Atlas VTT.

If your tabletop runs on Atlas VTT inside Obsidian, this plugin gives any MCP-capable agent programmatic hands on it: your token and map library, image reveals on the Atlas player window ("show the party this handout"), Atlas settings, and the live Fantasy Statblocks bestiary that fills Atlas tables with monsters — all as typed MCP tools.

What this is and isn't: it is a bridge for Atlas VTT setups. Atlas VTT (and the Local REST API plugin that hosts the MCP server) is required; there is nothing here without it. Fantasy Statblocks and Fantasy Content Generator are optional companions that complete an Atlas table — each feature degrades gracefully, and vtt_capabilities always reports exactly what is reachable.

Works with any client that speaks MCP — Claude Desktop, Claude Code, OpenCode, Cursor, VS Code, or anything else that can reach a Streamable HTTP endpoint. Everything stays on localhost, authenticated with your Local REST API key. Nothing leaves your machine.

How it works: this plugin does not host its own server. It uses the Local REST API with MCP plugin's public extension API (getPublicApi) to register tools and a REST subresource router into the MCP/REST server that plugin already runs. One endpoint, one API key, no extra ports.

Status: 0.1 — deliberately early. This is a first public release of an AI-built tool: it works and every documented behavior was measured, not assumed — but 0.x means "bugs and missing features are expected; finding them is the point." It ships with its regression suite (test/), and issues and pull requests are open and welcome — see CONTRIBUTING.md.

Requirements

• Obsidian desktop (the Local REST API plugin is desktop-only).

• Atlas VTT — the plugin this bridges.

• Local REST API with MCP v5.x, enabled. Its settings show the API key and ports; the MCP endpoint has been built in since v5.

• Optional: Fantasy Statblocks (for the bestiary tools), Fantasy Content Generator (for its commands).

Related MCP server: foundry-rest-api-mcp-server

Setup

1. Install and enable the required plugins

Settings → Community plugins → Browse → install and enable Atlas VTT and "Local REST API" (by Adam Coddington). In the REST plugin's settings, copy the API key and note the ports (defaults: HTTPS on 27124, plain HTTP on 27123 if "Enable insecure server" is on).

Tip: the plain-HTTP port avoids trusting the plugin's self-signed certificate and is the easiest to work with locally. The examples below assume it.

2. Install Atlas VTT MCP Bridge

Settings → Community plugins → Browse → "Atlas VTT MCP Bridge" → Install → Enable.

(Manual install: copy this folder to <vault>/.obsidian/plugins/atlas-vtt-mcp-bridge/, keeping main.js and manifest.json, then enable it in Community plugins.)

On enable you should see a notice: Atlas VTT MCP Bridge: 11 tools (7 typed), REST routes at /vault/<note>/vtt-bridge/.

3. Verify the bridge itself

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "http://127.0.0.1:27123/vault/<any-existing-note>/vtt-bridge/capabilities"

This reports that Atlas VTT was found, which companion plugins are present, which features are active, and any load-time errors. (<any-existing-note>: subresource routes mount under a real note path; any note works, e.g. index.md.)

4. Point your MCP client at it

The MCP endpoint is the Local REST API plugin's: http://127.0.0.1:27123/mcp/ (Streamable HTTP), with header Authorization: Bearer YOUR_API_KEY.

Claude Desktop (claude_desktop_config.json; Claude Desktop speaks stdio, so proxy with mcp-remote):

{
  "mcpServers": {
    "atlas-vtt": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://127.0.0.1:27123/mcp/",
               "--header", "Authorization: Bearer YOUR_API_KEY"]
    }
  }
}

OpenCode (opencode.json):

{
  "mcp": {
    "servers": {
      "Obsidian": {
        "type": "remote",
        "url": "http://127.0.0.1:27123/mcp/",
        "headers": { "Authorization": "Bearer YOUR_API_KEY" }
      }
    }
  }
}

Any other Streamable HTTP client: URL http://127.0.0.1:27123/mcp/, header Authorization: Bearer YOUR_API_KEY.

After (re)connecting, your client should list tools starting with vtt_. Note that clients snapshot the tool list at connect time — after (re)enabling the bridge, restart the agent session to see it.

5. Try it

“List the tokens in my Atlas asset library and show the Cleric on the player window.”

Tools (MCP)

REST endpoints

The same operations, plus multi-criteria queries, under /vault/<any-existing-note>/vtt-bridge/ (authenticated like every other route):

KEY=YOUR_API_KEY; BASE="http://127.0.0.1:27123/vault/index.md/vtt-bridge"
curl -s -H "Authorization: Bearer $KEY" "$BASE/assets?type=token&nameContains=cleric"
curl -s -H "Authorization: Bearer $KEY" "$BASE/bestiary?source=notes"
curl -s -H "Authorization: Bearer $KEY" "$BASE/settings?key=localPlayerView.showGrid"
curl -s -X POST -H "Authorization: Bearer $KEY" -H 'Content-Type: application/json' \
     -d '{"commandId":"atlas-vtt:send-map-to-player-view"}' "$BASE/command"

Design notes

• Safety. Plugin-owned state is written only through the owning plugin's service APIs, never by rewriting another plugin's files behind its back. Settings writes require the key to already exist (a typo can't litter Atlas's settings). The command runner only accepts the id prefixes of Atlas VTT and its two companion plugins. Read-only tools are annotated readOnlyHint: true.

• The live bestiary. Frontmatter-defined creatures are ephemeral in Fantasy Statblocks: held in memory keyed by note path, never written to its data.json. An empty monsters array there proves nothing — the bridge reads the live registry instead. If the bestiary is still resolving (or autoParse is off), it reports resolved: false plus the command that fixes it, rather than pretending there are no creatures.

• The player window. Atlas shows agent-revealed images on its player window, which only exists when mirroring a loaded map (atlas-vtt:send-map-to-player-view). Without one, Atlas accepts image requests but mounts nothing — the bridge detects this and returns ok:false with the repair step instead of a misleading success.

• Typed tool arguments. The Local REST API extension API validates tool arguments with its bundled Zod and rejects foreign schema objects (the "Zod trap"). The bridge satisfies the exact internal contracts it finds there — keyValidator._parse(input) at call time, _def.typeName/isOptional() at schema-generation time — with a tiny hand-built validator (zodish() in src/main.ts). If a future host ever rejects it, each tool degrades to a parameterless variant and records the failure in vtt_capabilities().diagnostics instead of disappearing.

• Reverse-engineered internals. Atlas VTT ships no public API; the bridge resolves its internal services by property name at call time (never cached across reloads) and vtt_capabilities reports what it found. A future Atlas release that renames internals shows up there first.

Troubleshooting

Compatibility

Built and tested against: Obsidian 1.13.x, Local REST API with MCP 5.3.1, Atlas VTT 0.4.2, Fantasy Statblocks 4.10.3, Fantasy Content Generator 1.2.4. The bridge uses only the extension API (getPublicApi, v3) plus at-call-time feature detection, so it loads harmlessly when a companion plugin is missing — vtt_capabilities shows what it can see.

Development

npm install
npm run dev      # esbuild watch → main.js
npm run build    # type-check + production bundle
npm test         # regression suite against a live Obsidian (see CONTRIBUTING.md)

Structure: src/main.ts (single entry point: registration, capability probe, bestiary/asset/settings/command implementations), test/bridge.test.mjs (the integration suite this release was verified with). Install into a test vault by copying manifest.json + main.js to <vault>/.obsidian/plugins/atlas-vtt-mcp-bridge/. To reload the plugin code during development, run the Obsidian command Reload app without saving (app:reload).

Contributions: PRs are open and welcome — CONTRIBUTING.md covers the dev loop, how to run the tests against your own vault, the one load-bearing trick (zodish()), and where help is most needed.

Provenance

This plugin was developed end-to-end with AI tooling, and it says so on purpose:

• The private prehistory (as the DSH Atlas Bridge) was created first in the DeepSeek Harness (Windows app, v0.2) using the DeepSeek v4.1 flash model.

• The work was then continued in OpenCode on a local machine using a quantized Qwen 3.8 Flash Next model, which produced the typed-arguments breakthrough, the first public release (0.1.0), documentation and tests.

It is offered in that same spirit: an agent-facing companion for Atlas VTT, built by agents, with every documented behavior measured against the installed plugins rather than assumed. Full history in CHANGELOG.md.

License

MIT — see LICENSE.