legendkeeper-mcp

Agenten stärken
Der eigene Befehl des Herausgebers. Kein PlugMCP-Endpunkt.
Host a copy with our keys and logs.
uvx legendkeeper-mcp==0.1.2Claude Code hat keinen Installationslink für einen lokalen Befehl. Kopieren Sie den Befehl unten und führen Sie ihn in einem Terminal aus.
LEGENDKEEPER_API_KEY=<secret> LEGENDKEEPER_READ_ONLY=<value> claude mcp add io.github.chase-roohms-legendkeeper-mcp -- uvx legendkeeper-mcp==0.1.2In einem Terminal ausführen.
{ "mcpServers": { "io.github.chase-roohms-legendkeeper-mcp": { "command": "uvx", "args": [ "legendkeeper-mcp==0.1.2" ], "env": { "LEGENDKEEPER_API_KEY": "<secret>", "LEGENDKEEPER_READ_ONLY": "<value>" } } }}claude_desktop_config.json
Remote-URL oder ein Befehl auf Ihrem Rechner? Worin sich die beiden Installationen unterscheiden
Auf PlugMCP ausführen
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
StartenAn 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! ...
api_request escape hatch reaches every other v3 endpoint.[[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.If-Match), so concurrent edits in the app are never silently
overwritten."3 March 1204"), templates, batch creation of up to 100
linked resources, and image uploads from disk or URL.Retry-After, idempotency keys on every POST so retries never
double-create, and rate-limit tracking.402 PAID_PLAN_REQUIRED otherwise.lk_… secret; it is shown only once.
list_tags falls back
to counting tags itself for Member keys), see member emails and save templates.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 withdocker 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>).
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.
Everything is configured with environment variables. CLI flags (--transport, --host, --port, --read-only)
override them.
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.
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.
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:
**Infobox**
*Facts*
- **Ruler:** [Princess Bubblegum](lk://resources/pb…)
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.
LEGENDKEEPER_READ_ONLY=true or --read-only) doesn't register write tools at all.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.If-Match) and retry once from a fresh
read on conflict.MCP_AUTH_TOKEN; compose binds to
127.0.0.1 only, with a read-only filesystem, all capabilities dropped and a non-root user.LEGENDKEEPER_UPLOAD_ROOT.lk_ab…wxyz) and never sent anywhere but LegendKeeper.
Signed upload URLs receive the image bytes, not the key.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
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:
ghcr.io/<owner>/legendkeeper-mcp,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.
MIT. LegendKeeper is a trademark of its respective owner; this project only uses its public API.
Read and build LegendKeeper worlds from AI assistants: wiki pages, maps, timelines, facts and tags.
{ "mcpServers": { "io.github.chase-roohms-legendkeeper-mcp": { "command": "uvx", "args": [ "legendkeeper-mcp==0.1.2" ], "env": { "LEGENDKEEPER_API_KEY": "<secret>", "LEGENDKEEPER_READ_ONLY": "<value>" } } }}Tools
Noch keine Tool-Liste. Remote-Server erhalten eine nach dem ersten Health-Check.
FAQ
Kopieren Sie auf dieser Seite die stdio-Konfiguration für Cursor, Claude Desktop, Claude Code oder VS Code. Sie nutzt die Installation des Herausgebers, keinen PlugMCP-Proxy.
Der Herausgeber nennt diese Umgebungsvariablen: LEGENDKEEPER_API_KEY, LEGENDKEEPER_READ_ONLY.
LegendKeeper läuft lokal über stdio.
Zuletzt geprüft: 2026-11-09. Read and build LegendKeeper worlds from AI assistants: wiki pages, maps, timelines, facts and tags.