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
search_documents	Full-text search, ranked snippets	read
get_document	Fetch one document with its markdown	read
list_documents	List docs (by collection / parent / author)	read
list_collections	List collections	read
list_comments	List comments on a document/collection	read
whoami	Current user + team	read
create_document	Create a document	write
update_document	Edit a document (replace/append/prepend/patch)	write
create_comment	Comment on a document	write

Set OUTLINE_MCP_READONLY=true to drop all write tools.

Setup

0. Prerequisites (once)

1. 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.

2. Install uv (a fast Python runner that launches the server):

   • macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
   • Windows (PowerShell): powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

   Then open a new terminal so uvx is on your PATH.

No clone needed for the recommended method below — uvx fetches the code from GitHub for you. Only the checkout-based methods (§3 script, §4 Claude Code) need git 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)
PY

Windows (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 uvx downloads 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-server

Press 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      # Windows

---

3. 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	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
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-server

---

5. 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)	MCP_ALLOW_OUTLINE_TOKEN_AUTH=true	their own Outline token	forwarded per caller
Gateway (shared)	MCP_AUTH_TOKEN=<secret>	the shared secret	OUTLINE_API_TOKEN
Open (private nets)	MCP_ALLOW_UNAUTHENTICATED=true	nothing	OUTLINE_API_TOKEN

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=true where writes aren't needed.

License

TBD (MIT or Apache-2.0) — chosen before the first published release.