MCP Outline Server

A Model Context Protocol server for interacting with Outline document management.

Features

Document operations: Search, read, create, edit, archive documents
Collections: List, create, manage document hierarchies
Comments: Add and view threaded comments
Backlinks: Find documents referencing a specific document
MCP Resources: Direct content access via URIs (outline://document/{id}, outline://collection/{id}, etc.)
Automatic rate limiting: Transparent handling of API limits with retry logic

Prerequisites

Before using this MCP server, you need:

An Outline account (cloud hosted or self-hosted)
API key from Outline web UI: Settings → API Keys → Create New
Python 3.10+ (for non-Docker installations)

Getting your API key: Log into Outline → Click your profile → Settings → API Keys → "New API Key". Copy the generated token.

Installation

Using uv (Recommended)

uvx mcp-outline

Using pip

pip install mcp-outline

Using Docker

docker run -e OUTLINE_API_KEY=<your-key> ghcr.io/vortiago/mcp-outline:latest

Or build from source:

docker buildx build -t mcp-outline .
docker run -e OUTLINE_API_KEY=<your-key> mcp-outline

Configuration

Variable	Required	Default	Notes
`OUTLINE_API_KEY`	Yes	-	Get from Outline web UI: Settings → API Keys → Create New
`OUTLINE_API_URL`	No	`https://app.getoutline.com/api`	For self-hosted: `https://your-domain/api`
`OUTLINE_READ_ONLY`	No	`false`	`true` = disable ALL write operations (details)
`OUTLINE_DISABLE_DELETE`	No	`false`	`true` = disable only delete operations (details)
`OUTLINE_DISABLE_AI_TOOLS`	No	`false`	`true` = disable AI tools (for Outline instances without OpenAI)
`MCP_TRANSPORT`	No	`stdio`	Transport mode: `stdio` (local), `sse` or `streamable-http` (remote)
`MCP_HOST`	No	`127.0.0.1`	Server host. Use `0.0.0.0` in Docker for external connections
`MCP_PORT`	No	`3000`	HTTP server port (only for `sse` and `streamable-http` modes)

Access Control

Configure server permissions to control what operations are allowed:

Read-Only Mode

Set OUTLINE_READ_ONLY=true to enable viewer-only access. Only search, read, export, and collaboration viewing tools are available. All write operations (create, update, move, archive, delete) are disabled.

Use cases:

Shared access for team members who should only view content
Safe integration with AI assistants that should not modify documents
Public or demo instances where content should be protected

Available tools:

Search & Discovery: search_documents, list_collections, get_collection_structure, get_document_id_from_title
Document Reading: read_document, export_document
Comments: list_document_comments, get_comment
Collaboration: get_document_backlinks
Collections: export_collection, export_all_collections
AI: ask_ai_about_documents (if not disabled with OUTLINE_DISABLE_AI_TOOLS)

Disable Delete Operations

Set OUTLINE_DISABLE_DELETE=true to allow create and update workflows while preventing accidental data loss. Only delete operations are disabled.

Use cases:

Production environments where documents should not be deleted
Protecting against accidental deletions
Safe content editing workflows

Disabled tools:

delete_document, delete_collection
batch_delete_documents

Important: OUTLINE_READ_ONLY=true takes precedence over OUTLINE_DISABLE_DELETE. If both are set, the server operates in read-only mode.

Adding to Your Client

Prerequisites: Install uv with pip install uv or from astral.sh/uv

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "mcp-outline": {
      "command": "uvx",
      "args": ["mcp-outline"],
      "env": {
        "OUTLINE_API_KEY": "<YOUR_API_KEY>",
        "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // Optional
      }
    }
  }
}

Add to Cursor

Go to Settings → MCP and click Add Server:

{
  "mcp-outline": {
    "command": "uvx",
    "args": ["mcp-outline"],
    "env": {
      "OUTLINE_API_KEY": "<YOUR_API_KEY>",
      "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // Optional
    }
  }
}

Add to VS Code

Create a .vscode/mcp.json file in your workspace with the following configuration:

{
  "servers": {
    "mcp-outline": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-outline"],
      "env": {
        "OUTLINE_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

For self-hosted Outline instances, add OUTLINE_API_URL to the env object.

Optional: Use input variables for sensitive credentials:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "outline-api-key",
      "description": "Outline API Key",
      "password": true
    }
  ],
  "servers": {
    "mcp-outline": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-outline"],
      "env": {
        "OUTLINE_API_KEY": "${input:outline-api-key}"
      }
    }
  }
}

VS Code will automatically discover and load MCP servers from this configuration file. For more details, see the official VS Code MCP documentation.

Add to Cline (VS Code)

In Cline extension settings, add to MCP servers:

{
  "mcp-outline": {
    "command": "uvx",
    "args": ["mcp-outline"],
    "env": {
      "OUTLINE_API_KEY": "<YOUR_API_KEY>",
      "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // Optional
    }
  }
}

Using pip instead of uvx

If you prefer to use pip instead:

pip install mcp-outline

Then in your client config, replace "command": "uvx" with "command": "mcp-outline" and remove the "args" line:

{
  "mcp-outline": {
    "command": "mcp-outline",
    "env": {
      "OUTLINE_API_KEY": "<YOUR_API_KEY>",
      "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // Optional
    }
  }
}

Docker Deployment (HTTP)

For remote access or Docker containers, use HTTP transport. This runs the MCP server on port 3000:

docker run -p 3000:3000 \
  -e OUTLINE_API_KEY=<YOUR_API_KEY> \
  -e MCP_TRANSPORT=streamable-http \
  ghcr.io/vortiago/mcp-outline:latest

Then connect from client:

{
  "mcp-outline": {
    "url": "http://localhost:3000/mcp"
  }
}

Note: OUTLINE_API_URL should point to where your Outline instance is running, not localhost:3000.

Tools

Note: Tool availability depends on your Access Control settings. Some tools are disabled in read-only mode or when delete operations are restricted.

Search & Discovery

search_documents(query, collection_id?, limit?, offset?) - Search documents by keywords with pagination
list_collections() - List all collections
get_collection_structure(collection_id) - Get document hierarchy within a collection
get_document_id_from_title(query, collection_id?) - Find document ID by title search

Document Reading

read_document(document_id) - Get document content
export_document(document_id) - Export document as markdown

Document Management

create_document(title, collection_id, text?, parent_document_id?, publish?) - Create new document
update_document(document_id, title?, text?, append?) - Update document (append mode available)
move_document(document_id, collection_id?, parent_document_id?) - Move document to different collection or parent

Document Lifecycle

archive_document(document_id) - Archive document
unarchive_document(document_id) - Restore document from archive
delete_document(document_id, permanent?) - Delete document (or move to trash)
restore_document(document_id) - Restore document from trash
list_archived_documents() - List all archived documents
list_trash() - List all documents in trash

Comments & Collaboration

add_comment(document_id, text, parent_comment_id?) - Add comment to document (supports threaded replies)
list_document_comments(document_id, include_anchor_text?, limit?, offset?) - View document comments with pagination
get_comment(comment_id, include_anchor_text?) - Get specific comment details
get_document_backlinks(document_id) - Find documents that link to this document

Collection Management

create_collection(name, description?, color?) - Create new collection
update_collection(collection_id, name?, description?, color?) - Update collection properties
delete_collection(collection_id) - Delete collection
export_collection(collection_id, format?) - Export collection (default: outline-markdown)
export_all_collections(format?) - Export all collections

Batch Operations

batch_create_documents(documents) - Create multiple documents at once
batch_update_documents(updates) - Update multiple documents at once
batch_move_documents(document_ids, collection_id?, parent_document_id?) - Move multiple documents
batch_archive_documents(document_ids) - Archive multiple documents
batch_delete_documents(document_ids, permanent?) - Delete multiple documents

AI-Powered

ask_ai_about_documents(question, collection_id?, document_id?) - Ask natural language questions about your documents

Resources

outline://collection/{id} - Collection metadata (name, description, color, document count)
outline://collection/{id}/tree - Hierarchical document tree structure
outline://collection/{id}/documents - Flat list of documents in collection
outline://document/{id} - Full document content (markdown)
outline://document/{id}/backlinks - Documents that link to this document

Development

Quick Start with Self-Hosted Outline

# Generate configuration
cp config/outline.env.example config/outline.env
openssl rand -hex 32 > /tmp/secret_key && openssl rand -hex 32 > /tmp/utils_secret
# Update config/outline.env with generated secrets

# Start all services
docker compose up -d

# Create API key: http://localhost:3030 → Settings → API Keys
# Add to .env: OUTLINE_API_KEY=<token>

Setup

git clone https://github.com/Vortiago/mcp-outline.git
cd mcp-outline
uv pip install -e ".[dev]"

Testing

# Run tests
uv run pytest tests/

# Format code
uv run ruff format .

# Type check
uv run pyright src/

# Lint
uv run ruff check .

Running Locally

uv run mcp-outline

Testing with MCP Inspector

Use the MCP Inspector to test the server tools visually via an interactive UI.

For local development (with stdio):

npx @modelcontextprotocol/inspector -e OUTLINE_API_KEY=<your-key> -e OUTLINE_API_URL=<your-url> uv run python -m mcp_outline

For Docker Compose (with HTTP):

npx @modelcontextprotocol/inspector http://localhost:3000

MCP Inspector

Architecture Notes

Rate Limiting: Automatically handled via header tracking (RateLimit-Remaining, RateLimit-Reset) with exponential backoff retry (up to 3 attempts). No configuration needed.

Transport Modes:

stdio (default): Direct process communication
sse: HTTP Server-Sent Events (use for web clients)
streamable-http: Streamable HTTP transport

Connection Pooling: Shared httpx connection pool across instances (configurable: OUTLINE_MAX_CONNECTIONS=100, OUTLINE_MAX_KEEPALIVE=20)

Troubleshooting

Server not connecting?

Check your API credentials:

# Test your API key
curl -H "Authorization: Bearer YOUR_API_KEY" YOUR_OUTLINE_URL/api/auth.info

Common issues:

Verify OUTLINE_API_KEY is set correctly in your MCP client configuration
Check OUTLINE_API_URL points to your Outline instance (default: https://app.getoutline.com/api)
For self-hosted Outline, ensure the URL ends with /api
Verify your API key hasn't expired or been revoked

Tools not appearing in client?

Read-only mode enabled? Check if OUTLINE_READ_ONLY=true is disabling write tools
Delete operations disabled? Check if OUTLINE_DISABLE_DELETE=true is hiding delete tools
AI tools missing? Check if OUTLINE_DISABLE_AI_TOOLS=true is disabling AI features
Restart your MCP client after changing environment variables

API rate limiting errors?

The server automatically handles rate limiting with retry logic. If you see persistent rate limit errors:

Reduce concurrent operations
Check if multiple clients are using the same API key
Contact Outline support if limits are too restrictive for your use case

Docker container issues?

Container won't start:

Ensure OUTLINE_API_KEY is set: docker run -e OUTLINE_API_KEY=your_key ...
Check logs: docker logs <container-id>

Can't connect from client:

Use 0.0.0.0 for MCP_HOST: -e MCP_HOST=0.0.0.0
Verify port mapping: -p 3000:3000
Check transport mode: -e MCP_TRANSPORT=streamable-http

Contributing

Contributions welcome! Please submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Built with MCP Python SDK
Uses Outline API for document management

Outline文档