# outline-mcp

![Python](https://img.shields.io/badge/python-3.12-blue?logo=python&logoColor=white)
![Docker](https://img.shields.io/badge/docker-ready-2496ED?logo=docker&logoColor=white)
![License](https://img.shields.io/badge/license-MIT-green)

MCP server for [Outline](https://www.getoutline.com/) — 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

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

Edit `.env`:

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

### 3. Start the server

```bash
docker compose up -d
```

Verify it's running:

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

## Connecting to Claude

### Claude Code

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

### Claude Desktop

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

```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:

```bash
# 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:

```bash
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