> ## Documentation Index
> Fetch the complete documentation index at: https://llmwiki.atomicstrata.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect llmwiki to Claude Desktop, Cursor, and Claude Code

> Set up the llmwiki MCP server to let Claude Desktop, Cursor, Claude Code, and other MCP agents ingest, compile, and query your wiki directly.

The llmwiki MCP server turns any MCP-compatible agent into a first-class wiki collaborator. Instead of scripting CLI calls and parsing stdout, agents can call structured tools - `compile_wiki`, `query_wiki`, `get_context_pack`, and more - and receive typed JSON results they can reason over. Start with `wiki_status`, then `get_context_pack` to retrieve evidence for your own reasoning without provider credentials. Use generation or write tools only when the task needs them.

This guide walks you through starting the server, wiring it into Claude Desktop and Cursor, and understanding exactly what your agents can do once connected.

## Prerequisites

* Node.js 24 or later on the MCP client's `PATH`
* llmwiki installed globally: `npm install -g llm-wiki-compiler`
* A wiki project directory (or an empty directory where one will be created)
* An LLM provider configured for tools that need one (see the provider configuration docs for `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)

## Setup

<Steps>
  <Step title="Start the MCP server">
    Run `llmwiki serve` from anywhere, pointing `--root` at your wiki project directory. The server uses stdio transport and requires no credentials at startup - read-only tools work immediately.

    ```bash theme={null}
    llmwiki serve --root /path/to/wiki-project
    ```

    The process stays running and speaks the MCP protocol over stdin/stdout. Your MCP client manages the lifecycle.
  </Step>

  <Step title="Add to Claude Desktop">
    Open your Claude Desktop MCP configuration file (`claude_desktop_config.json`) and add an `llmwiki` entry under `mcpServers`. The `npx` invocation launches the server on demand - you do not need to keep a separate terminal session open.

    ```json theme={null}
    {
      "mcpServers": {
        "llmwiki": {
          "command": "npx",
          "args": ["-y", "llm-wiki-compiler", "serve", "--root", "/path/to/wiki-project"],
          "env": {
            "ANTHROPIC_API_KEY": "sk-ant-..."
          }
        }
      }
    }
    ```

    Restart Claude Desktop after saving the file. The llmwiki tools will appear in Claude's tool picker.
  </Step>

  <Step title="Add to Cursor">
    Cursor uses the same MCP config format. Add the same JSON block to your Cursor MCP settings file. The `env` block is where you supply provider credentials - Cursor passes them through to the server process.

    ```json theme={null}
    {
      "mcpServers": {
        "llmwiki": {
          "command": "npx",
          "args": ["-y", "llm-wiki-compiler", "serve", "--root", "/path/to/wiki-project"],
          "env": {
            "ANTHROPIC_API_KEY": "sk-ant-..."
          }
        }
      }
    }
    ```
  </Step>

  <Step title="Verify with wiki_status">
    Ask Claude or your Cursor agent to call `wiki_status`. This tool is read-only and requires no credentials, so it works immediately and confirms the server is connected.

    A successful response looks like:

    ```json theme={null}
    {
      "pages": { "concepts": 12, "queries": 3, "total": 15 },
      "sources": 8,
      "lastCompiledAt": "2026-06-10T14:22:00Z",
      "stalePages": [],
      "staleCount": 0,
      "orphanedPages": [],
      "orphanedCount": 0,
      "stateStatus": "ok",
      "pendingCandidates": 0,
      "pendingChanges": [],
      "pendingChangesCount": 0
    }
    ```
  </Step>
</Steps>

## What agents can do

### Tools

The server exposes the tools below. Provider requirements are separate from write permissions: ingestion and OKF exchange can write files without an LLM provider.

| Tool | What it does | Credentials required |
| - | - | :-: |
| `ingest_source` | Fetch a URL or local file into `sources/` | No |
| `compile_wiki` | Run the incremental compile pipeline; returns page counts and slugs | Yes |
| `query_wiki` | Answer with optional `save` to request a page after fresh citation validation and the profile gate; refusal returns the answer with `publicationRefusal` and no saved slug | Yes |
| `search_pages` | Return full content of pages relevant to a question | Yes |
| `read_page` | Read a single page by slug (checks `concepts/` then `queries/`) | No |
| `lint_wiki` | Run quality checks; returns structured diagnostics | No |
| `wiki_status` | Page and source counts, stale/orphaned pages, `stateStatus`, `pendingCandidates` | No |
| `get_context_pack` | Build a token-budgeted evidence pack (primary pages, chunks, graph neighbors, citations, freshness, warnings, suggested actions) | No |
| `run_eval` | Score wiki quality - fast suite is credential-free; full suite LLM-judges citation samples | Fast: No / Full: Yes |
| `export_okf` | Export the wiki as an Open Knowledge Format bundle under a project-confined output path | No |
| `import_okf` | Preview or stage an Open Knowledge Format bundle from a project-confined path as review candidates | No |
| `verify_artifact` | Verify a hash-pinned artifact reference and return metadata, without its body | No |
| `list_workflow_actions` | List available workflow actions | No |
| `describe_workflow_action` | Inspect an action and its input contract | No |
| `run_workflow_action` | Run a declared action, capped at staged writes; cannot approve human gates | Depends on action |
| `workflow_run_status` | Inspect a workflow run | No |

**`get_context_pack` vs `query_wiki`:** these tools serve different purposes. `get_context_pack` *packages evidence* - it assembles a structured JSON envelope of relevant pages, semantic chunks, and citations that the agent uses for its own reasoning. `query_wiki` *generates an answer* - it calls the LLM and returns prose. Use `get_context_pack` when the agent needs grounded source material to reason over; use `query_wiki` when you want a finished answer.

`query_wiki` and `search_pages` fall back to selecting pages without embeddings when the embedding call fails, and report it as an `embedding-degraded` warning in the result instead of failing. `query_wiki`'s `pageIds` and `refs` name only pages whose content reached the answer model; a selected page that can't be read is named in a `page-hydration-dropped` warning.

`query_wiki` has no review option. Its existing no-save path returns the answer and advisory citations without publication checks. See [publication policy and recovery](/cli/query#publication-and-review-policy) before using `save: true`.

### MCP resources

Resources are passive read views of the wiki that agents can attach as context without calling a tool. All resources are read-only.

| URI | Returns |
| - | - |
| `llmwiki://index` | Full `wiki/index.md` (auto-generated table of contents) |
| `llmwiki://concept/{slug}` | A single concept page - frontmatter and body |
| `llmwiki://query/{slug}` | A single saved query page |
| `llmwiki://sources` | List of ingested source files with metadata |
| `llmwiki://state` | Compilation state - per-source hashes and last compile times |
| `llmwiki://eval/report` | The most recent eval report |
| `llmwiki://eval/history` | Trend table of past eval runs |

## Credentials per tool call

The server starts without credentials. Provider credentials are read from the `env` block in your MCP config and forwarded to each pipeline call:

* **Read-only and filesystem-only tools** (`read_page`, `lint_wiki`, `wiki_status`, `ingest_source`, `export_okf`, `import_okf`) - do not need provider credentials; normal path, project, and policy checks still apply.
* **LLM-dependent tools** (`compile_wiki`, `query_wiki`, `search_pages`) - require a valid provider credential (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.) in the environment at call time.
* **`get_context_pack`** - credential-free by default. When embeddings are available and provider credentials are present, semantic retrieval is used. Without credentials or an embedding store, the tool falls back to lexical ranking and surfaces an `embedding-store-missing` or `query-embedding-unavailable` warning in the response - it does not fail.
* **`run_eval`** - the `fast` suite (health score, citation coverage, corpus stats) runs without any credentials. The `full` suite adds LLM-judged citation scoring and requires a provider.

## `get_context_pack` details

`get_context_pack` accepts several optional parameters for tuning the evidence pack:

* `prompt` *(required)* - the task or question to assemble context for
* `budget` - approximate output token budget (default 8 000)
* `depth` - graph neighborhood traversal depth, `0`–`2` (default `1`; `0` disables graph expansion)
* `topPages` - maximum primary pages to include (default `5`, max `20`)
* `topChunks` - maximum semantic chunks to surface (default `8`, max `50`)
* `includeSources` *(opt-in)* - when `true`, materializes raw source line windows from claim-level citations

**`includeSources` is opt-in** because it returns raw content from files under `sources/`. Path confinement prevents reads outside `sources/`, but only enable source windows for agents you trust with the ingested source text.

## Using `ingest_source` safely

`ingest_source` accepts a URL or an absolute local file path. Because it performs a server-side fetch and local file read, it is a **trusted-input-only** primitive - pass only URLs and paths you control. For untrusted or user-supplied content, use the SDK's `ingestText` instead (see the [SDK guide](/guides/sdk)).

## OKF tools

`export_okf` and `import_okf` give agents structured Open Knowledge Format access without parsing CLI output.

* `export_okf` writes an OKF bundle. Its optional `out` path is confined under the project root.
* `import_okf` reads an OKF bundle from a project-confined `dir`. It supports `dryRun` and is always staging-only; MCP does not expose the trusted live-write import path.
* After `import_okf` stages pages, approve them with `llmwiki review list`, `llmwiki review show`, and `llmwiki review approve`.

<Tip>
  After an agent calls `compile_wiki`, check `wiki_status` and look at the `pendingCandidates` field. If your wiki has a review policy configured in `.llmwiki/config.json`, some pages may be held for human review rather than written directly. A non-zero `pendingCandidates` means the agent has queued work that needs your approval before those pages go live - run `llmwiki review list` to inspect them.
</Tip>

## Agent skill

The npm package ships an [Agent Skills](https://agentskills.io/specification) skill at `skills/llmwiki/SKILL.md`. It tells a skill-aware agent when a persistent wiki is worth building, and routes a connected agent to `wiki_status` and `get_context_pack` before any tool that writes or needs a provider. Copy or symlink the installed directory into your agent's skills directory; for Claude Code that is `~/.claude/skills/`:

```bash theme={null}
mkdir -p ~/.claude/skills
ln -s "$(npm root -g)/llm-wiki-compiler/skills/llmwiki" ~/.claude/skills/llmwiki
```

The skill never changes agent configuration on its own and does not grant publication approval; review candidates still go through `llmwiki review`.

## Next steps

* See [CLI reference: llmwiki serve](/cli/serve) for all server flags and transport options.
* For programmatic in-process control from TypeScript, see the [SDK guide](/guides/sdk).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.