llm-wiki-mcp

An MCP server for a plain-markdown "LLM wiki" vault — a knowledge base of notes with YAML frontmatter and Obsidian-style [[wiki-links]], maintained by an LLM librarian. No Obsidian app or plugin required: the server reads the files directly, so it works headless and unattended.

Tools

Tool	Access	What it does
search_wiki(query, limit=20)	read	Case-insensitive full-text + filename search; filename/title matches rank above body matches.
read_note(path)	read	One note: parsed YAML frontmatter, parse error (if any), and markdown body.
list_recent(n=10)	read	The n most recently modified notes, newest first (ISO 8601 UTC).
write_note(path, content, mode, dry_run=False)	gated write	create a new .md note or append to an existing one. No overwrite mode exists.
get_links(path)	read	Outbound [[wiki-links]] and backlinks (matched by filename stem, title, or aliases).

Safety model

• Path traversal is blocked. Every path resolves inside the vault root or the call fails — absolute paths, .. segments, and symlink escapes included.
• Writes are append/create only. There is no overwrite, no delete, and no rename. create refuses existing files; append refuses missing ones. dry_run=true previews without touching disk.
• raw/ is immutable. The vault's source-material directory rejects all writes.
• Only .md files are writable.
• Malformed notes degrade cleanly. Broken YAML frontmatter comes back as a frontmatter_error string with the body intact — never a traceback.
• Links in code don't count. [[links]] inside code fences and inline code are ignored by the link graph (they're examples, not references).

Setup

Requires Python 3.11+ and uv.

git clone <this-repo> llm-wiki-mcp
cd llm-wiki-mcp
uv sync

Point the server at your vault (the directory that contains wiki/):

# PowerShell
$env:LLM_WIKI_VAULT = "C:\path\to\your\vault"
# bash
export LLM_WIKI_VAULT=/path/to/your/vault

Run it standalone (stdio transport):

uv run llm-wiki-mcp

Register with Claude Code

claude mcp add llm-wiki -e LLM_WIKI_VAULT="C:\path\to\your\vault" -- uv run --directory "C:\path\to\llm-wiki-mcp" llm-wiki-mcp

Then in any Claude Code session: "search the wiki for X", "read wiki/concepts/foo.md", "append a journal line to wiki/log.md".

The gardener (scheduled agent)

llm-wiki-gardener is a Claude agent (built on claude-agent-sdk) that tends the vault through this MCP server. Its entire tool surface is the five tools above — no shell, no direct file access. Each pass lints recent notes against the vault's conventions, flags orphans and broken links, proposes crystallization candidates, and files ONE dated report note at wiki/journal/gardener/YYYY-MM-DD.md via the gated write_note. It never edits existing notes.

uv run llm-wiki-gardener --vault /path/to/vault            # one pass
uv run llm-wiki-gardener --vault /path/to/vault --dry-run  # preview, no write

Authentication rides the local Claude Code CLI login. To run weekly on Windows:

schtasks /create /tn llm-wiki-gardener /sc weekly /d SUN /st 21:00 /tr "uv run --directory C:\path\to\llm-wiki-mcp llm-wiki-gardener --vault C:\path\to\vault"

Development

uv run pytest        # test suite runs against a synthetic fixture vault (tests/fixtures/vault)
uv run ruff check .  # lint
uv run ruff format . # format

The fixture vault is fully synthetic — no real notes, names, or content. Keep it that way.

Design notes

Prior art (what exists, what we adopted, why this was built anyway) is documented in docs/prior-art.md.

License

MIT