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

Related MCP server: kObsidian MCP

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