LegendKeeper

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.

1. 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 . Images placed in ./uploads can be uploaded with upload_image (source: /uploads/ ).

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:

| [[Name]], [[Name\|label]], [label](lk://resources/ ) | mention (link to anothe