MCP Outline Server

> ## 📢 Official Outline MCP Server Available

>

> Outline now ships an official MCP server — we recommend using it.

> Read the docs.

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.

Quick Start

One-Click Install

Click a button to install with interactive API key prompt:

Manual Install

Install with uv (recommended), pip, or Docker:

uvx mcp-outline          # using uv
pip install mcp-outline   # using pip

# using Docker
docker run -e OUTLINE_API_KEY= ghcr.io/vortiago/mcp-outline:latest

Then add to your MCP client config (works with VS Code, Claude Desktop, Cursor, and others):

{
  "inputs": [
    {
      "id": "outline_api_key",
      "type": "promptString",
      "description": "Enter OUTLINE_API_KEY",
      "password": true
    },
    {
      "id": "outline_api_url",
      "type": "promptString",
      "description": "Outline API URL (optional, for self-hosted)",
      "password": false
    }
  ],
  "servers": {
    "mcp-outline": {
      "command": "uvx",
      "args": ["mcp-outline"],
      "env": {
        "OUTLINE_API_KEY": "${input:outline_api_key}",
        "OUTLINE_API_URL": "${input:outline_api_url}"
      }
    }
  }
}

Claude Code

claude mcp add mcp-outline uvx mcp-outline

Installing the repo as a plugin instead also bundles the

`outline-explorer` agent (fast read-only wiki exploration) and the

`outline` skill (Outline conventions: mermaidjs fences, document

structure, editing workflows).

Claude Desktop

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

{
  "mcpServers": {
    "mcp-outline": {
      "command": "uvx",
      "args": ["mcp-outline"],
      "env": {
        "OUTLINE_API_KEY": "",
        "OUTLINE_API_URL": ""
      }
    }
  }
}

Setup guides for more clients: Docker (HTTP), Cline, Codex, Windsurf, and others

Configuration

Access Control

Read-only mode takes precedence over disable-delete. See Configuration Guide for details.

Tools

> Note: Tool availability depends on your access control settings.

Search & Discovery

• `search_documents(query, collection_id?, limit?, offset?, statusFilter?)` - Search documents by keywords with pagination. Defaults to published documents; pass `statusFilter` with `draft`, `archived`, and/or `published` to include other states
• `list_recently_updated_documents(date_filter?, collection_id?, status_filter?, limit?, offset?)` - List documents by most recent change, newest first (e.g. "what changed this week"). `date_filter` windows by last change: `day`/`week`/`month`/`year` (default `week`). Defaults to published documents
• `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, offset?, limit?)` - Get document content with optional line-range pagination
• `export_document(document_id)` - Export document as markdown

Document Navigation

• `get_document_toc(document_id)` - Get table of contents with heading structure and line numbers
• `read_document_section(document_id, heading)` - Read a specific section by heading match (case-insensitive substring)

Document Management

• `create_document(title, collection_id, text?, parent_document_id?, publish?)` - Create new document
• `update_document(document_id, title?, text?, append?)` - Replace full document content (append mode available)

Document Editing

• `edit_document(document_id, edits, save?)` - String-match editing with batched replacements; `save=False` stages changes locally, `save=True` on the final call pushes all changes
• `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

git clone https://github.com/Vortiago/mcp-outline.git
cd mcp-outline
uv sync --group dev

uv run poe test-unit          # unit tests
uv run poe test-integration   # integration tests (starts MCP server via stdio)
uv run poe test-e2e           # E2E tests (requires Docker)

See Development Guide for self-hosted Outline setup, MCP Inspector, and more.

Troubleshooting

Server not connecting? Test your API key:

curl -H "Authorization: Bearer YOUR_API_KEY" YOUR_OUTLINE_URL/api/auth.info

See Troubleshooting Guide for common issues with tools, rate limiting, and Docker.

Contributing

Contributions welcome! See CONTRIBUTING.md for setup instructions.

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