outline-mcp-server
This server exposes an Outline knowledge base as an MCP server, enabling AI clients to interact with documents, collections, comments, and user info via natural language.
Read operations:
Search documents — Full-text search with ranked snippets, supporting filters by collection, user, date range, and status (draft/archived/published)
Get a document — Fetch a single document (including full markdown content) by UUID, URL ID, or share ID
List documents — Browse documents scoped by collection, parent document, author, or status
List collections — Browse all collections, with optional name/status filtering
List comments — View comments on a document or collection, optionally including anchor text
Who am I — Retrieve the authenticated user's identity and team info
Write operations:
Create a document — Create a new document with a title, markdown content, icon, publication status, and optionally assign it to a collection or parent document
Update a document — Edit an existing document using one of four modes:
replace(full overwrite),append(add to end),prepend(add to beginning), orpatch(targeted find-and-replace of a specific section)Create a comment — Add a comment to a document with markdown or rich-text, supporting threaded replies and inline anchoring to specific text
Note: All write tools can be disabled by setting
OUTLINE_MCP_READONLY=true.
Provides tools to search, read, write, and comment on documents in an Outline knowledge base via the Outline REST API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@outline-mcp-server Search for documents about API design"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
outline-mcp-server
A Model Context Protocol server that exposes an Outline knowledge base to MCP clients — Claude Desktop, Claude.ai, ChatGPT Desktop, and others — so you can search, read, write, and comment on your documents through natural language.
It's a thin, near-stateless proxy over Outline's public REST API: point it at an Outline URL and an
API token and it works against any instance, self-hosted or cloud. See
docs/design-spec.md for the full design.
Tools
Tool | Does | Mode |
| Full-text search, ranked snippets | read |
| Fetch one document with its markdown | read |
| List docs (by collection / parent / author) | read |
| List collections | read |
| List comments on a document/collection | read |
| Current user + team | read |
| Create a document | write |
| Edit a document ( | write |
| Comment on a document | write |
Set OUTLINE_MCP_READONLY=true to drop all write tools.
Setup
Related MCP server: Outline MCP Server
0. Prerequisites (once)
Get an Outline API token — in Outline, click your avatar → Settings → API Tokens → New token. Copy it (looks like
ol_api_…). Each person uses their own token; the server only ever acts with that user's permissions.Install
uv(a fast Python runner that launches the server):macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | shWindows (PowerShell):
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Then open a new terminal so
uvxis on your PATH.
No clone needed for the recommended method below —
uvxfetches the code from GitHub for you. Only the checkout-based methods (§3 script, §4 Claude Code) needgit clone.
1. Claude Desktop — one command, no clone (recommended)
Set your Outline URL + token, then paste the block for your OS. It writes the outline server into
Claude Desktop's config file (correct per-OS path handled automatically; merges without clobbering
other servers), pointing Claude at the GitHub build via uvx.
macOS / Linux (Terminal):
export OUTLINE_API_URL='https://your-outline.example.com/api'
export OUTLINE_TOKEN='ol_api_PASTE_YOUR_TOKEN'
python3 - <<'PY'
import json, os, platform, shutil
from pathlib import Path
def cfg_path():
s = platform.system()
if s == "Darwin":
return Path.home() / "Library/Application Support/Claude/claude_desktop_config.json"
if s == "Windows":
base = os.environ.get("APPDATA") or (Path.home() / "AppData/Roaming")
return Path(base) / "Claude" / "claude_desktop_config.json"
base = os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config")
return Path(base) / "Claude" / "claude_desktop_config.json"
uvx = shutil.which("uvx") or os.path.expanduser("~/.local/bin/uvx")
p = cfg_path(); p.parent.mkdir(parents=True, exist_ok=True)
cfg = json.loads(p.read_text() or "{}") if p.exists() else {}
cfg.setdefault("mcpServers", {})["outline"] = {
"command": uvx,
"args": ["--from", "git+https://github.com/Geoffrey313/outline-mcp", "outline-mcp-server"],
"env": {
"OUTLINE_API_URL": os.environ["OUTLINE_API_URL"],
"OUTLINE_API_TOKEN": os.environ["OUTLINE_TOKEN"],
},
}
p.write_text(json.dumps(cfg, indent=2))
print("Wrote", p, "\nuvx:", uvx)
PYWindows (PowerShell):
$env:OUTLINE_API_URL='https://your-outline.example.com/api'
$env:OUTLINE_TOKEN='ol_api_PASTE_YOUR_TOKEN'
@'
import json, os, platform, shutil
from pathlib import Path
def cfg_path():
s = platform.system()
if s == "Darwin":
return Path.home() / "Library/Application Support/Claude/claude_desktop_config.json"
if s == "Windows":
base = os.environ.get("APPDATA") or (Path.home() / "AppData/Roaming")
return Path(base) / "Claude" / "claude_desktop_config.json"
base = os.environ.get("XDG_CONFIG_HOME") or (Path.home() / ".config")
return Path(base) / "Claude" / "claude_desktop_config.json"
uvx = shutil.which("uvx") or "uvx"
p = cfg_path(); p.parent.mkdir(parents=True, exist_ok=True)
cfg = json.loads(p.read_text() or "{}") if p.exists() else {}
cfg.setdefault("mcpServers", {})["outline"] = {
"command": uvx,
"args": ["--from", "git+https://github.com/Geoffrey313/outline-mcp", "outline-mcp-server"],
"env": {
"OUTLINE_API_URL": os.environ["OUTLINE_API_URL"],
"OUTLINE_API_TOKEN": os.environ["OUTLINE_TOKEN"],
},
}
p.write_text(json.dumps(cfg, indent=2))
print("Wrote", p, "\nuvx:", uvx)
'@ | python -Then fully quit Claude Desktop (macOS ⌘Q / Windows: exit from the tray, not just close the window) and reopen. The Outline tools appear under the tools/🔌 icon; local servers are also listed under Settings → Developer.
First launch can be slow (~15–25s) while
uvxdownloads the build the first time — Claude may time out and the server won't show. Fix: pre-warm the cache once in your terminal, then restart Claude:OUTLINE_API_URL='https://your-outline.example.com/api' OUTLINE_TOKEN='ol_api_…' \ "$(command -v uvx)" --from git+https://github.com/Geoffrey313/outline-mcp outline-mcp-serverPress Ctrl-C once you see the
Outline MCP (stdio)line — it's cached now.
To update later: uv cache clean then restart Claude (re-pulls from GitHub).
2. Claude Desktop — interactive script (from a checkout)
If you've cloned the repo, this does the same thing with prompts (and backs up any existing config):
python3 scripts/setup.py # macOS / Linux
python scripts\setup.py # Windows3. Claude Desktop — manual
Prefer to edit the file yourself? Open the config for your OS and add the outline block below.
OS | Config file |
macOS |
|
Windows |
|
Linux | no official Claude Desktop — use Claude Code (§4) |
{
"mcpServers": {
"outline": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/outline-mcp-server", "outline-mcp-server"],
"env": {
"OUTLINE_API_URL": "https://your-outline.example.com/api",
"OUTLINE_API_TOKEN": "ol_api_…"
}
}
}
}Replace the path and token, save, then fully quit and reopen Claude Desktop. The Outline tools
appear under the tools/search icon. (After publishing to PyPI, this simplifies to
"command": "uvx", "args": ["outline-mcp-server"].)
4. Claude Code (any OS, including Linux)
One command from the repo folder:
claude mcp add outline \
-e OUTLINE_API_URL=https://your-outline.example.com/api \
-e OUTLINE_API_TOKEN=ol_api_… \
-- uv run --directory "$(pwd)" outline-mcp-server5. ChatGPT (Desktop or web) — remote connector
ChatGPT connects to hosted (remote) MCP servers only — it can't launch a local process like Claude Desktop can. So you first deploy the server (see Hosted deployment below), then in ChatGPT:
Settings → Connectors → Add / Create (available on paid plans / developer mode) → point it at
your server's URL, e.g. https://outline-mcp.example.com/mcp, and provide your Outline token as
the Bearer credential. macOS and Windows desktop apps use the same connector.
6. Remote server from Claude Desktop (via mcp-remote)
To connect Claude Desktop to a hosted instance instead of running it locally, use the
mcp-remote bridge (needs Node.js):
{
"mcpServers": {
"outline": {
"command": "npx",
"args": [
"-y", "mcp-remote",
"https://outline-mcp.example.com/mcp",
"--header", "Authorization:Bearer ${OUTLINE_TOKEN}"
],
"env": { "OUTLINE_TOKEN": "ol_api_…" }
}
}
}(The ${OUTLINE_TOKEN} indirection avoids a header-parsing quirk with spaces in some shells.)
Hosted deployment (Streamable HTTP)
Run one container for a team behind a reverse proxy. Pick exactly one inbound auth strategy:
Strategy | Set | Clients send | Upstream token |
Passthrough (per-user) |
| their own Outline token | forwarded per caller |
Gateway (shared) |
| the shared secret |
|
Open (private nets) |
| nothing |
|
MCP_ALLOWED_HOSTS must be set to the public host(s), e.g. outline-mcp.example.com.
cp .env.example .env # edit it
docker compose up -d --build # joins the external `backend` network as `outline-mcp`Point your reverse proxy (e.g. Nginx Proxy Manager → http://outline-mcp:9000) at it with
streaming enabled — Streamable HTTP streams SSE-style over plain HTTP (not a WebSocket):
proxy_buffering off;
proxy_request_buffering off;
proxy_read_timeout 3600s;
proxy_send_timeout 3600s;If you front it with Cloudflare on a Tailscale IP, the DNS record must be grey-cloud
(DNS-only) — a 100.x address isn't publicly routable, so Cloudflare can't proxy it. Note that a
Tailscale-only endpoint is reachable by desktop apps on your tailnet, but not by web connectors
(claude.ai / ChatGPT web), which call from outside it.
Configuration
All settings are environment variables — see .env.example for the full list and
defaults. Nothing is hardcoded; everything is centralized in src/outline_mcp/config.py.
Security notes
Tokens are never written to disk or logged; in passthrough mode they live in a request-scoped context (plus an ephemeral, TTL-bounded session cache for bridges that drop the header).
The server fails fast at startup on an ambiguous/unusable auth configuration.
An Outline API token carries its user's full permissions — Outline API keys are not scoped. Prefer a dedicated token (and, if possible, a limited-permission service user), and use
OUTLINE_MCP_READONLY=truewhere writes aren't needed.
License
TBD (MIT or Apache-2.0) — chosen before the first published release.
Available Tools
9 toolscreate_commentB
Add a comment to a document. Provide markdown text (preferred) or rich-text data.
Inputs: document_id (required), data, text, anchor_text, +3 more.
create_documentC
Create a document. Publishing requires a collection or parent document to live in.
Inputs: title (required), icon, text, publish, +3 more.
get_documentB
Fetch a single document (including its markdown text) by UUID, urlId, or share id.
Inputs: id (required), share_id.
list_collectionsC
List collections, optionally filtered by name or status.
Inputs: sort, limit, query, offset, +2 more.
list_commentsB
List comments, optionally scoped to a document or collection.
Inputs: limit, offset, document_id, collection_id, +1 more.
list_documentsC
List documents, optionally scoped to a collection, parent, or author.
Inputs: sort, limit, offset, user_id, +4 more.
search_documentsC
Full-text search documents by keyword. Returns ranked snippets with their documents.
Inputs: query (required), sort, limit, offset, +6 more.
update_documentC
Update a document. edit_mode=patch requires find_text to locate the edit.
Inputs: id (required), text, title, publish, +2 more.
whoamiA
Return the authenticated user and team for the current token.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool clearly targets a distinct resource and action: document CRUD, comments, collections, search, and user info. No overlap in purpose.
All tools follow a consistent verb_noun pattern (e.g., create_document, list_comments), with 'whoami' as a minor but acceptable exception.
9 tools cover the core operations for a knowledge base server (documents, comments, collections, search, auth) without being excessive or insufficient.
Missing key lifecycle operations: no delete for documents or comments, no collection creation/update/deletion. Notable gaps that could cause agent failures.
Maintenance
Related MCP Connectors
KnowMan MCP server: search, ask, save and read your Knowledge Base from any MCP client.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Turn outlines and hierarchical notes into interactive mind maps through a hosted remote MCP server.
Related MCP Servers
- AlicenseAqualityCmaintenanceA Model Context Protocol server that enables AI assistants like Claude to interact with Outline document services, supporting document searching, reading, creation, editing, and comment management.38716 PyPI159MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables reading, writing, and searching documents in Outline via its API. It supports document management, full-text search, and collection organization using Markdown formatting.834 npm17MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server for interacting with Outline document management, supporting search, read, create, edit, archive documents, collections, comments, and backlinks.30MIT
- AlicenseNot gradedqualityFmaintenanceA Model Context Protocol server that enables AI agents to manage documents, collections, comments, and users in Outline through its API.513 npm121MIT