legendkeeper-mcp

An MCP server that lets AI assistants (Claude, Copilot, Cursor, …) read and build your LegendKeeper worlds: wiki pages, infobox facts, map pins, timelines, tags, templates and images, through LegendKeeper's official v3 REST API.

Unofficial. This project is not made, endorsed or supported by LegendKeeper. It runs locally on your machine with your own API key.

You: Create a tavern called The Drunken Dragon in Waterdeep, give it an infobox with its owner and
     a pin on the city map, and mention it on Volo's page.
Claude: (search → create_resource → set_facts → create_map_feature → write_page) Done! ...

Contents

• Features
• Requirements
• Quick start
• Client setup
• Configuration
• Tools
• How pages are edited (Markdown)
• Safety
• Troubleshooting
• Development
• Releasing

Features

• 31 curated tools designed for LLMs. Resources accept names as well as ids, and errors explain how to fix them. An api_request escape hatch reaches every other v3 endpoint.
• Pages as Markdown, both ways. [[Wiki Links]] become real LegendKeeper mentions. Callouts, GM-only secrets, collapsible sections, task lists, tables and images are supported. Blocks Markdown can't express (infoboxes, embeds, collections…) are preserved verbatim on rewrite. See How pages are edited.
• Section-level editing: append, prepend, replace or extend one heading's section without touching the rest of the page. Every write is version-checked (If-Match), so concurrent edits in the app are never silently overwritten.
• Structured worldbuilding: infobox and sidebar facts, map pins/regions/paths (lat/lng or image pixels), timeline events and lanes (human dates such as "3 March 1204"), templates, batch creation of up to 100 linked resources, and image uploads from disk or URL.
• Multiple worlds from one server (one API key per world), plus a read-only mode.
• Two transports: stdio for desktop clients, or a long-running Docker container serving streamable HTTP behind a bearer token.
• Robust client: retries with backoff, honors Retry-After, idempotency keys on every POST so retries never double-create, and rate-limit tracking.
• Contract-tested: the test suite runs against a fake API that validates every request and response against LegendKeeper's published OpenAPI spec. A weekly CI job re-checks against the latest spec.

Requirements

1. A LegendKeeper project whose owner is on a paid plan. LegendKeeper only accepts API keys for those (a trial does not count), and answers 402 PAID_PLAN_REQUIRED otherwise.
2. An API key: in LegendKeeper open your project, go to Project Settings → Developers → API Keys, name the key, pick a role and create it. Copy the lk_… secret; it is shown only once.
   • Member keys can read and write content.
   • Admin keys can also see and create hidden resources and GM secrets, read tags (list_tags falls back to counting tags itself for Member keys), see member emails and save templates.
   • A key never has more rights than its creator, and only works in its own project.
3. One of: uv (recommended), Docker, or Python ≥ 3.11 with pip.

Quick start

Pick one. All of them read the key from LEGENDKEEPER_API_KEY.

uvx (no install):

LEGENDKEEPER_API_KEY=lk_... uvx legendkeeper-mcp check   # verify the key

Docker:

docker run -i --rm -e LEGENDKEEPER_API_KEY=lk_... ghcr.io/chase-roohms/legendkeeper-mcp:latest check

pip:

pip install legendkeeper-mcp
legendkeeper-mcp check

check prints the world each configured key opens, then exits. Without check, the command starts the MCP server on stdio, which is what desktop clients launch for you (see below).

Before the first PyPI release, use uvx --from git+https://github.com/chase-roohms/legendkeeper-mcp legendkeeper-mcp, or build the image yourself with docker build -t legendkeeper-mcp ..

Long-running HTTP server (Docker Compose):

cp .env.example .env              # set LEGENDKEEPER_API_KEY and MCP_AUTH_TOKEN (openssl rand -hex 32)
docker compose up -d              # serves http://localhost:8000/mcp, bound to 127.0.0.1 only
curl http://localhost:8000/healthz

Point HTTP-capable clients at http://localhost:8000/mcp with the header Authorization: Bearer <MCP_AUTH_TOKEN>. Images placed in ./uploads can be uploaded with upload_image (source: /uploads/<file>).

Client setup

Ready-to-use files are in examples/.

Claude Desktop: add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude:

{
  "mcpServers": {
    "legendkeeper": {
      "command": "uvx",
      "args": ["legendkeeper-mcp"],
      "env": { "LEGENDKEEPER_API_KEY": "lk_your_key_here" }
    }
  }
}

VS Code (.vscode/mcp.json, the key is prompted for and stored securely):

{
  "inputs": [{ "type": "promptString", "id": "lk-key", "description": "LegendKeeper API key", "password": true }],
  "servers": {
    "legendkeeper": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "LEGENDKEEPER_API_KEY", "ghcr.io/chase-roohms/legendkeeper-mcp:latest"],
      "env": { "LEGENDKEEPER_API_KEY": "${input:lk-key}" }
    }
  }
}

Claude Code:

claude mcp add legendkeeper --env LEGENDKEEPER_API_KEY=lk_... -- uvx legendkeeper-mcp

Cursor, Windsurf, others: same command/args/env as Claude Desktop, in the client's MCP config file.

Configuration

Everything is configured with environment variables. CLI flags (--transport, --host, --port, --read-only) override them.

Multiple worlds

LEGENDKEEPER_API_KEY_HOMEBREW=lk_aaa
LEGENDKEEPER_API_KEY_STRAHD=lk_bbb
LEGENDKEEPER_DEFAULT_PROJECT=homebrew

Every tool takes an optional project argument ("strahd"), and list_projects shows what is configured.

Tools

The server also exposes two MCP resources the assistant can read: legendkeeper://guides/markdown (the Markdown dialect) and legendkeeper://guides/style (conventions for tags, icons, infoboxes, pins and events, adapted from LegendKeeper's style guide). Write tools are annotated so clients can ask for confirmation; destructive tools also require confirm: true.

How pages are edited (Markdown)

LegendKeeper stores pages as a tree of typed blocks, not Markdown. This server converts in both directions:

When a page is read, blocks Markdown can't express appear as readable regions:

<!-- lk:keep id="kq3…" kind="infobox" -->
**Infobox**
*Facts*
- **Ruler:** [Princess Bubblegum](lk://resources/pb…)
<!-- /lk:keep -->

Writing those marker lines back preserves the original block exactly. Edits inside the region are ignored with a warning; use set_facts, or read with opaque_blocks: "json" to edit the raw JSON. In replace mode, paragraphs and other blocks whose content didn't change are matched to the originals. Their ids and any styling Markdown can't show (colors, alignment, callout icons) are kept.

The converter is fuzz-tested with Hypothesis for exact round trips, including tricky punctuation, nested marks and escaping.

Safety

• Read-only mode (LEGENDKEEPER_READ_ONLY=true or --read-only) doesn't register write tools at all.
• Confirmation: delete_* tools and api_request DELETE refuse to run without confirm: true. Deleted resources go to LegendKeeper's trash and can be brought back with restore_resource.
• No lost updates: page writes send the version they were based on (If-Match) and retry once from a fresh read on conflict.
• No duplicates on retry: every POST carries an idempotency key.
• HTTP mode refuses to listen on a non-loopback address without MCP_AUTH_TOKEN; compose binds to 127.0.0.1 only, with a read-only filesystem, all capabilities dropped and a non-root user.
• Uploads: only real JPEG/PNG/GIF/WebP files (checked by content) up to the size limit, optionally restricted to LEGENDKEEPER_UPLOAD_ROOT.
• Secrets: keys are never logged (only masked as lk_ab…wxyz) and never sent anywhere but LegendKeeper. Signed upload URLs receive the image bytes, not the key.

Troubleshooting

Development

uv sync                       # create .venv with dev dependencies
uv run pytest                 # full test suite (downloads the OpenAPI spec once into tests/.cache)
uv run ruff check . && uv run ruff format --check . && uv run mypy
uv run legendkeeper-mcp       # run from source
npx @modelcontextprotocol/inspector uv run legendkeeper-mcp   # poke at it interactively

Testing layers:

• tests/test_markdown*.py: converter unit tests and Hypothesis property tests (round trips must be exact).

• tests/test_tools.py: every tool end to end through a real MCP client session against tests/fake_lk.py, an in-memory LegendKeeper. When the OpenAPI spec is available, every request must hit a real route with a schema-valid body, and every fake response must match the documented response schema. CI requires the spec (LK_REQUIRE_SPEC=1).

• tests/test_live.py: opt-in smoke tests against the real API. Write tests build everything under one [mcp-test] … sandbox resource and delete it afterwards:

  LEGENDKEEPER_LIVE_TESTS=1 LEGENDKEEPER_LIVE_WRITE=1 LEGENDKEEPER_API_KEY=lk_... uv run pytest tests/test_live.py -v
  

Project layout:

src/legendkeeper_mcp/
  client.py      async HTTP client (auth, retries, idempotency, pagination, errors)
  config.py      environment configuration
  service.py     per-project sessions, project-id discovery, cached resource index
  documents.py   reading/writing documents (page Markdown, maps, timelines, boards)
  markdown/      Markdown <-> block conversion (parse, render, merge)
  tools/         MCP tool definitions
  server.py      server assembly; http_app.py streamable HTTP + bearer auth; cli.py entry point

Releasing

CI runs on every push and PR: lint, mypy, tests on Linux/macOS/Windows (Python 3.11-3.13), a wheel build, and a Docker build with stdio/HTTP smoke tests.

To release, bump version in pyproject.toml, src/legendkeeper_mcp/__init__.py and server.json (the server and package versions plus the image tag), update CHANGELOG.md, commit, then git tag v0.2.0 && git push --tags. The release workflow then:

1. verifies the tag matches the package version and reruns CI,
2. publishes to PyPI using trusted publishing,
3. pushes a multi-arch (amd64/arm64) image with SBOM and provenance to ghcr.io/<owner>/legendkeeper-mcp,
4. creates a GitHub release with the built distributions,
5. publishes server.json to the official MCP Registry as io.github.chase-roohms/legendkeeper-mcp (GitHub OIDC login, no secret needed). The registry checks ownership through the mcp-name comment at the top of this README, which PyPI shows as the package description, and the io.modelcontextprotocol.server.name label on the Docker image.

One-time setup: on PyPI, add a pending trusted publisher for project legendkeeper-mcp → this repository, workflow release.yml, environment pypi, and create a pypi environment in the repository settings. GHCR needs no setup. After the first push, make the package public in its GitHub package settings.

License

MIT. LegendKeeper is a trademark of its respective owner; this project only uses its public API.