llm-wiki-mcp

Serve an LLM-maintained markdown wiki to agents over MCP.

If you keep a knowledge base in the shape Andrej Karpathy described — immutable raw sources, a wiki of markdown pages an LLM maintains, and a schema doc describing the conventions — this makes it queryable from any MCP client, without the agent having to walk your directory tree.

uvx llm-wiki-mcp --wiki ~/my-wiki

It is strictly read-only. It never writes to your wiki.

Why not just point the agent at the folder?

Because an agent given a directory reads the wrong things in the wrong order. It globs, opens files whole, and burns context rediscovering structure you already wrote down. This server front-loads the parts that are cheap and decisive: a curated index, one-line descriptions for every page, a tag vocabulary, and a best-match lookup that returns one page instead of forty snippets.

It also passes your wiki's own conventions doc through as the MCP server instructions — so a remote agent that has never opened your repo still follows your rules about linking, attribution, and what the page types mean.

Related MCP server: WikiStrata

Install

uv tool install llm-wiki-mcp          # or: pipx install llm-wiki-mcp
uv tool install 'llm-wiki-mcp[ask]'   # plus server-side synthesis

Register it with a client — for Claude Code:

claude mcp add my-wiki -- llm-wiki-mcp --wiki ~/my-wiki

Or in claude_desktop_config.json / any MCP client config:

{
  "mcpServers": {
    "my-wiki": {
      "command": "llm-wiki-mcp",
      "args": ["--wiki", "/absolute/path/to/wiki"]
    }
  }
}

Check what it found before wiring anything up:

llm-wiki-mcp --wiki ~/my-wiki --info

What it expects

Almost nothing. A directory of markdown files.

Page types are discovered, not configured. A page's type is its frontmatter type if it declares one, and otherwise the directory it lives in. So concepts/, people/, notes/ — whatever you use — become filters automatically. Filters tolerate singular and plural (--page_type concept finds concepts/).

Frontmatter is plain YAML. Only type and title really matter; description and tags are what make the cheap tools useful:

---
title: Grounding Data
description: Structured facts a publisher exposes to agents, rather than prose
type: concept
tags: [structured-news, publishing]
---

description is load-bearing. It's what list_pages shows and what find_page ranks on, so a page without one is half-invisible. Keep it to one line.

Tools

Tools that would always fail aren't registered at all — a tool that returns "not configured" costs the client context and invites a wasted call.

find_page vs search_wiki

search_wiki is ripgrep: every hit, as snippets. find_page returns one whole page, plus the runners-up by name so an agent can pivot.

Ranking weights title and slug — the page's identity — far above tags and description, and length-normalizes them. This matters more than it sounds: a page about a person almost never repeats their name in its own description, so without that weighting an entity's own page loses to every source that cites it. Short query tokens must match exactly (otherwise the matches authenticity); longer ones match by containment in either direction, so plurals find singulars.

Validation

A wiki written by an agent across many sessions doesn't fail by crashing — it drifts. A page never makes it into the index. A link's target gets renamed. A description picks up a colon and stops being valid YAML, so every consumer that isn't a hand-rolled parser goes blind to it.

llm-wiki-mcp --wiki ~/my-wiki --validate
llm-wiki-mcp --wiki ~/my-wiki --validate --level error   # what a hook should run

Errors mean malformed — broken for any consumer: invalid YAML, frontmatter opened and never closed, duplicate slugs that make a wikilink ambiguous. Warnings mean degraded — still serves, but worse: no type, title, description or tags; a page missing from the index; an index entry pointing at a page that doesn't exist; a missing source; a wikilink split across lines by hard-wrapping. Notes are informational: over-long descriptions, and unresolved [[red links]] — aggregated per target with a citation count, so the top of that list is a ranked backlog of pages worth writing.

Absent metadata is deliberately not an error. This server infers a title from the filename and a type from the directory, so a page without them still works — and a checker that fails on what its own server handles fine is a checker people turn off. A minimal wiki with no index, no log, and bare markdown pages passes a hook gating on errors.

Exit codes: 0 clean, 1 errors, 2 couldn't run. --strict fails on warnings too. A ready-made git hook is in examples/pre-commit.

Two deliberate choices worth knowing about. Red links are notes, not warnings — in a living wiki most are pages you haven't written yet, and one finding per mention buries everything else. And a referenced source that is absent but gitignored is a note explaining why, not a warning: keeping large PDFs out of git is a normal policy, and a check that's mostly false positives teaches you to ignore the whole category.

Transports

stdio by default — what most MCP clients expect, and the client is the parent process, so there's nothing to authenticate.

HTTP for serving a wiki to agents on other machines:

LLM_WIKI_TOKEN=$(openssl rand -base64 32) llm-wiki-mcp --http --port 8848

Requires a bearer token; refuses to start without one. Install the http extra. DNS-rebinding protection is off by default (the typical client is a CLI agent behind a token on a trusted network, not a browser) — set LLM_WIKI_ALLOWED_HOSTS to turn on the allowlist.

The ask tool

With ANTHROPIC_API_KEY set and the ask extra installed, ask(question) runs a turn-capped sub-agent over the same read-only tools and returns an answer citing [[wikilinks]]. The index is pinned into a cached system prefix, so repeated questions reuse it.

Use it when you want a finished answer rather than raw pages. Everything else works without it, and without any API key.

Configuration

Every flag has an environment variable. Flags win.

Relation to OKF

Google Cloud's Open Knowledge Format describes a very similar artifact: markdown plus YAML frontmatter, type required, index.md and log.md reserved. A Karpathy-format wiki that fills in description is already close to an OKF bundle at the metadata layer. The notable divergence is links — OKF uses relative markdown links, this expects [[wikilinks]], which is what Obsidian and most LLM-maintained wikis actually use. NRK's okf-mcp serves OKF bundles and is worth a look if that's your format.

Development

uv sync --all-extras
uv run pytest

License

GNU General Public License v2.0. See LICENSE.