outline-mcp

MCP server for Outline — gives Claude the ability to search and read documents from your Outline instance.

Tools

Tool	Description
search_documents	Full-text search across all documents. Returns title, excerpt, and URL for each result.
read_document	Reads the full content of a document in Markdown. Accepts document ID or URL.
list_collections	Lists all available collections in the workspace.

Requirements

• Docker and Docker Compose
• An Outline API token (see below)

Setup

1. Get your API token

In Outline: Settings → API Tokens → Create token

2. Clone and configure

git clone https://github.com/ngarbezza/outline-mcp.git
cd outline-mcp
cp .env.example .env

Edit .env:

OUTLINE_URL=https://your-outline-instance.com
OUTLINE_API_TOKEN=your_token_here

3. Start the server

docker compose up -d

Verify it's running:

curl http://localhost:8000/health
# {"status": "ok", "server": "outline-mcp"}

Connecting to Claude

Claude Code

claude mcp add outline --transport sse http://localhost:8000/sse

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "outline": {
      "url": "http://localhost:8000/sse"
    }
  }
}

Restart Claude Desktop after saving.

Claude.ai (web)

Claude.ai requires a publicly accessible URL. Use a tunnel to expose your local server:

# Option A: cloudflared (recommended, free)
cloudflared tunnel --url http://localhost:8000

# Option B: ngrok
ngrok http 8000

Then go to Claude.ai → Settings → Integrations → Add MCP and enter the tunnel URL.

Note: The tunnel URL changes every time you restart it. For a stable setup, configure a named cloudflared tunnel or use ngrok with a reserved domain.

Usage examples

Once connected, you can ask Claude things like:

• "Search Outline for our onboarding process"
• "What does the API design guidelines document say?"
• "List all collections in Outline"
• "Read the document at https://outline.yourcompany.com/doc/..."

Troubleshooting

curl /health returns connection refused The container isn't running. Check with docker compose ps and inspect logs with docker compose logs.

Claude says the tool is unavailable

• Claude Desktop: make sure you restarted the app after editing the config file.
• Claude Code: run claude mcp list to verify the server is registered.
• All clients: confirm the server is running with curl http://localhost:8000/health.

401 Unauthorized errors from Outline Your API token is invalid or expired. Generate a new one in Outline under Settings → API Tokens.

403 Forbidden on specific documents The token belongs to a user that doesn't have access to that collection. Check permissions in Outline.

Search returns no results Outline's search indexes documents asynchronously. Newly created documents may take a few minutes to appear. Also verify your token has read access to the collections you're searching.

Tunnel URL keeps changing (Claude.ai) Use a named cloudflared tunnel with a fixed subdomain, or run the MCP server on a VPS and point Claude.ai directly to it.

Development

To run the server locally without Docker:

pip install -r requirements.txt
export OUTLINE_URL=https://your-outline-instance.com
export OUTLINE_API_TOKEN=your_token_here
python src/server.py

License

MIT