Outline MCP

outline-mcp

Tree-structured knowledge base as an MCP server.

LLM sessions are ephemeral. outline-mcp gives them a persistent, editable knowledge tree — sections and content nodes that can be browsed (toc), annotated with properties, and evolved across sessions. Nodes with inject=true are automatically included in session context.

Quick Start

Books live in a Postgres database you run yourself. outline-mcp is a personal project published as-is: there is no hosted instance and no bundled database.

cargo install --path crates/outline-mcp

export OUTLINE_MCP_DATABASE_URL=postgres://user:pass@host:5432/outline outline-mcp migrate # create / update the schema; run once per upgrade outline-mcp # stdio

The server refuses to start when no database is configured, when the database cannot be reached (the message says whether the host is unreachable, the login was rejected, or the database does not exist), or when migrate has not been run against it. --database-url overrides the environment variable on every subcommand.

Claude Code (~/.claude.json)

{

"mcpServers": { "outline": { "command": "outline-mcp", "env": { "OUTLINE_MCP_DATABASE_URL": "postgres://user:pass@host:5432/outline" } } } }

Shared server (many devices)

--mcp-http serves the same tools over MCP's streamable HTTP transport. Every write is one database transaction with a per-book version check, so several server processes or devices can share one database.

outline-mcp --mcp-http                          # 127.0.0.1:8486

outline-mcp --mcp-http --bind 127.0.0.1:9000

Point clients at /mcp on that address:

{

"mcpServers": { "outline": { "type": "http", "url": "http://127.0.0.1:8486/mcp" } } }

Binding beyond loopback requires a token. Startup is refused without one, before any listener is opened:

OUTLINE_MCP_HTTP_TOKEN=<token> outline-mcp --mcp-http --bind 0.0.0.0:8486

Every request must then carry Authorization: Bearer — set it wherever your MCP client configures request headers. TLS termination is a reverse-proxy concern. Logs go to stderr in both transports; stdout stays reserved for the stdio protocol channel.

Browser view

--mcp-http also serves a read-only browser view at /ui/: the shelf, each book's table of contents (inject / status / verification / pending-revision / link markers; archived subtrees hidden unless asked), node pages (rendered body, properties, links both ways, the pending revision with its diff, history), text search (which also matches a UUID prefix of 8+ hex characters, and # such as #2-3 opens that node; the shelf's search box searches every book at once, and a node page shows its #n and 8-character id as separate click-to-select snippets) and book history. It never writes, runs no script and loads nothing from other hosts.

When OUTLINE_MCP_HTTP_TOKEN is set, the browser asks for HTTP Basic credentials: any user name, the token as the password. Without a token (loopback binds only) the view answers only requests whose Host is localhost, 127.0.0.1 or [::1]. The stdio transport has no browser view.

Service templates for running this as a daemon live in contrib/systemd/ and contrib/launchd/ (both take the database URL from their environment block). docs/runbooks/ covers hosting on Fly.io with an unmanaged Fly Postgres app (fly-io-deploy.md, config in contrib/fly/fly.toml), importing a pre-Postgres shelf (data-migration.md) and an end-to-end smoke checklist (multi-device-smoke.md).

Workflow

shelf  →  select_book  →  toc  →  node_create / node_update / node_move

node_batch_move / node_batch_update / node_query checklist / import / init / book_update / book_delete / gen_routing snapshot_create / snapshot_list / snapshot_restore / snapshot_delete node_history / dump node_locate (which book holds an id; needs no selected book) book_lint / book_stats (read-only health) node_verify (curation: verification dates) link_add / link_remove / links (curation: typed links) revision_propose / revision_show / revision_approve / revision_reject / revisions_pending (curation: review)

1. `init` — Create a new empty book
2. `node_create` — Add sections and content nodes (with optional properties); the result carries the new node's UUID, ready for the batch tools
3. `toc` — View the table of contents with numbered IDs (e.g. 1, 2-3). Supports filter by properties, max_depth (depth from the book root; 1 = root level only) and limit; a last line counts the nodes left out. Archived nodes and their subtrees are hidden (counted on a last line) unless include_archived: true, which shows them marked [archived]
4. `select_book` — Select a book. Nodes with inject=true property have their body auto-appended (draft and archived nodes, and everything under an archived section, excluded; the TOC it prints hides archived subtrees like toc)
5. `checklist` — Export a section (or the whole book) as a Markdown checklist with checkboxes. Archived subtrees are left out unless include_archived: true (or subtree_root is itself archived)
6. `node_update` — Edit title, body, type, placeholder, properties, or status of a node. Status is active, draft (not written yet) or archived (retired: kept readable, but not injected and hidden from toc / node_query unless asked for)
7. `node_move` — Relocate or delete nodes; descendants go along and are listed in the result. dry_run: true shows every node that would move or be removed (old → new positions) without changing anything. A remove records a delete in history for the node and each descendant
8. `node_batch_move` — Move multiple nodes in a single atomic call (requires UUID or UUID-prefix IDs; to delete a node, use node_move with action: "remove"); also takes dry_run
9. `node_batch_update` — Update title/body/type/properties/status on multiple nodes atomically
10. `node_query` — Search nodes by property values, status (active/draft/archived), type (section/content), text (case-insensitive substring of title or body, CJK included, with a snippet of the first body match), or verified_before (nodes never verified or last verified before a date / datetime / millis); optionally include body in results. Archived nodes come back only with status: "archived" or include_archived: true
11. `import` — Import a book from a previously exported JSON file, restoring status, verification, links and pending revisions. Node ids in the file are kept, so re-importing a book's own export changes only what differs; new_ids: true imports a copy with fresh ids (links between imported nodes are remapped). Links to nodes not in the file, and pending revisions that break the revision rules, are dropped and reported. The result counts nodes created, updated and deleted (nodes of the book that are not in the file are deleted). A file exported from one section (marked in the file, or recognized from its node ids for exports older than the marker) is refused unless force: true, since it would replace the whole book
12. `gen_routing` — Generate a Markdown routing table from nodes with routing property across all books
13. `snapshot_create` / `snapshot_list` / `snapshot_restore` / `snapshot_delete` — Full book versioning (create, list, restore, delete one snapshot; a labeled snapshot needs force: true to delete)
14. `node_history` — View per-node change log with before/after diffs
15. `dump` — Export full book as JSON file

15a. `node_locate` — Find which book holds a node, by UUID or a prefix of at least 8 hex digits (the short id); searches every book and needs no selected book. Archived books are skipped unless include_archived: true; archived nodes of a searched book are listed with their status

1. `book_delete` — Delete a book with its nodes, history and snapshots (cannot be undone). The slug is required; a book with any nodes, history or snapshots needs force: true, and dry_run: true only reports what would be removed. A write to the book between the check and the delete makes the delete fail without removing anything
2. `book_update` — Change a book's title and / or max_depth (slug required). Lowering max_depth below an existing node's depth is refused and names that node; the change appears in book_history as a book_update entry
3. `book_lint` — Read-only structural checks on a book (slug defaults to the selected book): content nodes at the root, similar titles (Jaccard over title words; character pairs for CJK; threshold default 0.6; pairs where both titles are a single token are skipped unless the titles are identical), property keys differing only by case / _ / - / spaces, sections without children, drafts not updated for stale_days (default 90), and links whose target is not in the book (dangling_links). Archived nodes and everything under an archived section are ignored by every check. checks runs a subset; limit (default 50) caps findings per check and counts the rest; format: "json" for programs
4. `book_stats` — Read-only numbers for a book: node counts, max / mean depth, children per section (max, mean, histogram), counts by status, injected nodes, update recency, distinct property keys, links; format: "json" for programs
5. `node_verify` — Record that nodes were confirmed to still match reality (node_ids, optional by): sets their verification time to now without touching content or last-edited time; one history entry per node, one commit. Pair with node_query verified_before to list what nobody has confirmed lately
6. `link_add` / `link_remove` / `links` — Typed links between nodes of a book (rel such as supersedes, superseded_by, see_also, merged_from; any 1–40 of a-z 0-9 _ -). Links follow the target's id, so moving it keeps them; removing a node drops the links pointing at it (each holder gets an update in history, in the same commit, and the result says how many were dropped). links lists outgoing links and backlinks; node_query takes linked_to (+ link_rel) and its JSON carries links / backlinks (with each endpoint's status, archived included). A link change is recorded in history but, like node_verify, leaves the node's updated_at alone
7. `revision_propose` / `revision_show` / `revision_approve` / `revision_reject` / `revisions_pending` — Changes under review. revision_propose attaches a proposed title / body / properties change (by, note optional) to a node without changing it: injection, toc, dump and every read keep the current content until approval. One pending revision per node (replace: true swaps it); archived nodes take none. revision_show gives a diff against the current content (title, unified body diff, properties added / changed / removed) and warns when the node changed since; revision_approve applies it (validated like node_update) as one history entry, refusing a stale one unless force: true; revision_reject drops it; revisions_pending lists them. Proposing and rejecting are recorded in history without touching updated_at. node_query shows a pending revision's summary, book_lint reports stale_proposals (older than stale_days, outdated, or left on a node archived since — those can only be rejected), book_stats counts them

Node IDs

toc assigns hu