← Docs hub

MCP server — tool reference

The llmwiki MCP server (python3 -m llmwiki.mcp) exposes six production tools over stdio (JSON-RPC 2.0). Connect it from Claude Code, Cursor, Codex, or any MCP client so agents can search, read, lint, sync, export, and add to your wiki without shelling out to the CLI. Every tool is implemented in llmwiki/mcp/server.py; telemetry is local-only under <vault>/usage/ (see State persistence and the Analytics MCP table in UI reference).

Tools

Tool Purpose
wiki_search Find, list, filter, and extract wiki content (unified search surface)
wiki_read_page Read one page by vault-relative path
wiki_health Run lint checks and return headline wiki totals
wiki_sync Pull new agent sessions into raw/sessions/ (dry-run by default)
wiki_export Return a built site/ export (llms-txt, jsonld, …)
wiki_add Proxy for CLI add: land one URL, file, or literal content under raw/docs/ (default raw + site rebuild; synth opt-in)

Dispatch is controlled by mode (or by supplying question alone, which implies extract mode).

mode=match (default)

Literal substring search over wiki pages (and optionally raw/sessions/).

Argument Required Description
term yes* Case-insensitive substring to find in titles, paths, and bodies
list_sources no When true, list raw/sessions/ metadata instead of searching
project no With list_sources=true, filter sessions whose project slug contains this string
kind no Restrict to one frontmatter type (source, entity, concept, project, synthesis)
include_raw no Also scan raw/sessions/ (default false)
format no text (default) or json

* Not required when list_sources=true.

The site's quick search mirrors this mode. The ⌘K command palette's Wiki result group uses the same deterministic, containment-checked corpus walk — every readable .md under wiki/ except archive/, with the same 4 MiB per-file and 50 MiB aggregate input limits — and the same matching rules: literal case-insensitive substring, name matches (title or path) before body-only matches, each sorted by path, the same kind filter, and the same 200-page / 200-matching-line output caps. A term typed on the site and the same term given to wiki_search return the same retained pages in the same order. The site warns when its built corpus hit an input limit.

What still differs is reach and presentation, not results: the site never scans raw/sessions/ (the browser has no include_raw), it searches the corpus as of the last llmwiki build rather than the vault on disk, and a result row folds its matching lines after the third. A wiki page the site has no reader page for is listed but is not clickable. mode=extract and mode=filter have no site equivalent and stay assistant-only. See UI reference for the palette's two-group layout.

mode=extract

Answer a natural-language question from wiki/index.md, wiki/overview.md, and matching pages.

Argument Required Description
question yes Question or keywords
max_pages no Cap on returned pages (default 5)

mode=filter

Metadata filters over loaded wiki pages.

filter_by Required args Optional args
confidence — min_confidence (default 0.0), max_confidence (default 1.0)
lifecycle state —
tag — tag (drill into one tag), min_count (default 1)

wiki_health

Same JSON payload as llmwiki lint --json (summary, issues, total_pages, disabled_rules, ran), plus a totals object:

Field Meaning
wiki_pages Pages loaded for lint
sources Source pages under wiki/sources/ (or type: source)
pending_candidates Markdown stubs in wiki/candidates/ (excluding _context.md)

Optional: rules (subset of checks), min_refs (broken-link threshold; default matches harvest).

wiki_sync

Defaults to dry-run. To write, pass dry_run: false and confirm: true.

Wall-clock budget defaults to 120 seconds, overridable via mcp.tool_timeouts.wiki_sync in config.json (see configuration-reference.md and Tool timeouts).

wiki_export

format is one of llms-txt, llms-full-txt, jsonld, sitemap, rss, manifest, or list (catalog of files present under site/). Run llmwiki build first when exports are missing.

wiki_add

Thin proxy onto the same shared run_add orchestration as CLI llmwiki add (#273 / #311). Defaults match the CLI: write raw doc(s) under the resolved vault's raw/docs/ and rebuild the site; do not synthesize wiki/sources/ unless synthesize is true. Each new import is one complete Markdown file (including long documents); synthesis chunks in memory to the backend budget and stitches one wiki source page. Legacy multi-piece vaults use llmwiki migrate whole-document-storage — see cli.md.

Exactly one of url, path, or content starts an add. To read an add that already started, pass operation_id alone and omit those three.

Argument Required Description
operation_id poll only Id from a timed-out add. Pass alone (no url / path / content) to read progress and the terminal outcome; combining it with a source is rejected.
url one of three HTTP(S) URL to fetch and convert
path one of three Local file path to convert
content one of three Literal markdown/text — uses the piped-text path (frontmatter source: "piped"), same as CLI llmwiki add -; never a tempfile provenance
title no Override title derivation
project no Group under raw/docs/<project>/
tags no Extra frontmatter tags (array)
note no Blockquote prepended to the body
synthesize no Opt in to synthesize wiki source pages after add (default false; mirrors CLI --synthesize)
no_build no Skip the site rebuild after add (default false; mirrors CLI --no-build)

Source-layer guardrail: use the user's named path, URL, or text. Do not reconstruct input from existing wiki pages (wiki/sources/ or other derived pages) unless the user asked.

When the document lands under raw/docs/ but the post-add site build fails, wiki_add still returns success with the written paths and a warning — reserve isError for genuine add failures that finish inside the budget. Pass no_build: true when you need a faster round-trip and will rebuild later.

Wall-clock budget for the whole add (including site build) defaults to 120 seconds, overridable via mcp.tool_timeouts.wiki_add. When the call exceeds that budget it returns a running operation_id instead of a failed add — poll wiki_add with that id alone (or llmwiki queue status --id) for progress and the final outcome, including whether a retry is safe. Do not decide from the vault filesystem. Raise the timeout for a large source or when synthesize is on.

Tool timeouts

Long-running MCP tools share one config section:

{
  "mcp": {
    "tool_timeouts": {
      "wiki_add": 120,
      "wiki_sync": 120
    }
  }
}
Key Default Applies to
mcp.tool_timeouts.wiki_add 120 wiki_add (convert + optional synth + site build)
mcp.tool_timeouts.wiki_sync 120 wiki_sync subprocess

Missing or invalid values fall back to 120. For latency-sensitive add callers that do not need an immediate site refresh, pass no_build: true.

Migration from retired tools (#196)

Retired tool Use instead
wiki_query wiki_search with mode=extract or question
wiki_list_sources wiki_search with mode=match, list_sources=true
wiki_confidence wiki_search with mode=filter, filter_by=confidence
wiki_lifecycle wiki_search with mode=filter, filter_by=lifecycle
wiki_category_browse wiki_search with mode=filter, filter_by=tag
wiki_lint wiki_health
wiki_dashboard wiki_health (totals field)
wiki_entity_search (removed in 2.0) wiki_search with mode=match and optional kind

There are no alias stubs — calling a retired name returns an unknown-tool error. Historical telemetry rows keep the logged tool name; aggregation folds retired names into the canonical six-tool surface (see cli.md).

Keyboard shortcuts

⌘K / Ctrl+KOpen command palette
/Focus search
g hGo to home
g pGo to projects
g sGo to sessions
j / kNext / prev row (tables)
?Show this help
EscClose dialogs

Structured queries

Mix key:value filters with free text in the palette:

type:sessionOnly session pages
project:llm-wikiFilter by project name (substring)
model:claudeFilter by model name (substring)
date:>2026-03-01Sessions after a date
date:<2026-04-01Sessions before a date
tags:rustPages mentioning a tag/topic
sort:dateSort results by date (newest first)

Example: type:session project:llm-wiki date:>2026-04 sort:date