MCP Outline Server

You can run and connect to the MCP Outline Server to manage Outline documents, collections, comments, and more through an MCP client. This server exposes document operations, collection management, backlinks, and AI-assisted tools, with flexible transport options for local or remote usage.

How to use

You interact with the server from an MCP client by starting the local server process or by running it in a container, then pointing your client to the correct transport method and URL. Choose a transport mode based on your environment: stdio for local, or streamable HTTP for remote access. Once connected, you can search, read, create, edit, archive, and manage documents and collections, add comments, view backlinks, and optionally use AI-powered queries.

How to install

# Prerequisites
- Python 3.10+ (for non-Docker installations)
- Optional: Docker if you prefer containerized usage

# Installation methods
# 1) Install via uvx (recommended for local development)
uvx mcp-outline

# 2) Install via pip
pip install mcp-outline

# 3) Docker deployment (HTTP transport)
docker run -p 3000:3000 \
  -e OUTLINE_API_KEY=<YOUR_API_KEY> \
  -e MCP_TRANSPORT=streamable-http \
  ghcr.io/vortiago/mcp-outline:latest

# Optional: Build from source and run locally (if you prefer)
git clone https://github.com/Vortiago/mcp-outline.git
cd mcp-outline
uvx pip install -e ".[dev]"  # install dependencies including dev tools

# Start the server (using stdio transport by default)
uv run mcp-outline

Configuration

Configure access and behavior using environment variables. Examples shown pull values from your Outline instance and control access. You can enable read-only mode, disable delete operations, and switch transport modes.

# Common configuration (examples)
# 1) StdIO (local) configuration snippet shown in client setup
{
  "mcp-outline": {
    "command": "uvx",
    "args": ["mcp-outline"],
    "env": {
      "OUTLINE_API_KEY": "<YOUR_API_KEY>",
      "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>"  // Optional for self-hosted Outline
    }
  }
}

# 2) Alternative stdio configuration using the binary directly after installation
{
  "mcp-outline": {
    "command": "mcp-outline",
    "env": {
      "OUTLINE_API_KEY": "<YOUR_API_KEY>",
      "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>"  // Optional
    }
  }
}

Troubleshooting

If you cannot connect, verify your API key and Outline URL, ensure the server is running, and confirm the transport mode matches what your client expects. Restart the client after changing environment variables.

# Quick checks
curl -H "Authorization: Bearer YOUR_API_KEY" <YOUR_OUTLINE_URL>/api/auth.info

# Troubleshooting tips
# - Ensure OUTLINE_API_KEY is set in your MCP client
# - Confirm OUTLINE_API_URL ends with /api for self-hosted instances
# - For container setups, expose port 3000 and map correctly

Notes on features and behavior

The server automatically handles rate limiting by observing response headers and retrying failed requests with exponential backoff. You can operate in read-only mode to restrict write actions, disable delete operations, and optionally disable AI tools depending on your deployment.

Developer quick start

# Quick self-hosted workflow
# 1) Prepare environment
cp config/outline.env.example config/outline.env
openssl rand -hex 32 > /tmp/secret_key

# 2) Start services
docker compose up -d

# 3) Create API key and wire it into the environment
# Access at http://localhost:3030 and add an API key under Settings → API Keys

Available tools

search_documents

Search documents by keywords with optional collection scope and pagination.

list_collections

List all document collections.

get_collection_structure

Retrieve the hierarchical structure of a collection.

get_document_id_from_title

Find a document ID by its title within a collection.

read_document

Fetch full document content in markdown.

export_document

Export a document as markdown.

create_document

Create a new document in a collection.

update_document

Update a document, with optional append mode.

move_document

Move a document to a different collection or parent.

archive_document

Archive a document.

unarchive_document

Restore a document from archive.

delete_document

Delete or move a document to trash (config dependent).

restore_document

Restore a document from trash.

list_archived_documents

List all archived documents.

list_trash

List all documents in trash.

add_comment

Add a threaded comment to a document.

list_document_comments

View comments on a document with optional pagination.

get_comment

Get details of a specific comment.

get_document_backlinks

Find documents that link to a given document.

create_collection

Create a new collection.

update_collection

Update a collection's properties.

delete_collection

Delete a collection.

export_collection

Export a collection in a chosen format.

export_all_collections

Export all collections.

batch_create_documents

Create multiple documents at once.

batch_update_documents

Update multiple documents at once.

batch_move_documents

Move multiple documents to a new collection or location.

batch_archive_documents

Archive multiple documents.

batch_delete_documents

Delete multiple documents in a single operation.

ask_ai_about_documents

Ask natural language questions about your documents.