Skip to content
Back to search

mcp-outline

MCP serverGitHubIncomplete

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/vortiago--mcp-outline/badge.svg)](/listings/vortiago--mcp-outline)

HTML

<a href="/listings/vortiago--mcp-outline"><img src="/api/listings/vortiago--mcp-outline/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

One-Click Install

Click a button to install with interactive API key prompt:

[![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=mcp-outline&inputs=%5B%7B%22id%22%3A%22outline_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20OUTLINE_API_KEY%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22outline_api_url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Outline%20API%20URL%20(optional%2C%20for%20self-hosted)%22%2C%22password%22%3Afalse%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-outline%22%5D%2C%22env%22%3A%7B%22OUTLINE_API_KEY%22%3A%22%24%7Binput%3Aoutline_api_key%7D%22%2C%22OUTLINE_API_URL%22%3A%22%24%7Binput%3Aoutline_api_url%7D%22%7D%7D) [![Install in VS Code Insiders](https://img.shields.io/badge/Install_in-VS_Code_Insiders-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=mcp-outline&inputs=%5B%7B%22id%22%3A%22outline_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20OUTLINE_API_KEY%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22outline_api_url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Outline%20API%20URL%20(optional%2C%20for%20self-hosted)%22%2C%22password%22%3Afalse%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-outline%22%5D%2C%22env%22%3A%7B%22OUTLINE_API_KEY%22%3A%22%24%7Binput%3Aoutline_api_key%7D%22%2C%22OUTLINE_API_URL%22%3A%22%24%7Binput%3Aoutline_api_url%7D%22%7D%7D&quality=insiders)

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=<your-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}"
      }
    }
  }
}

<details> <summary>Claude Code</summary>

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). </details>

<details> <summary>Claude Desktop</summary>

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

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

</details>

Setup guides for more clients: [Docker (HTTP), Cline, Codex, Windsurf, and others](docs/client-setup.md)

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 22 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "mcp-outline",
  3. "owner": {
  4. "name": "Vortiago",
  5. "url": "https://github.com/Vortiago"
  6. },
  7. "metadata": {
  8. "description": "Outline knowledge base integration for Claude Code"
  9. },
  10. "plugins": [
  11. {
  12. "name": "mcp-outline",
  13. "source": "./",
  14. "description": "Connect Claude Code to Outline for document search, reading, creation, and management",
  15. "version": "1.11.0",
  16. "author": {
  17. "name": "Vortiago"
  18. },
  19. "license": "MIT"
  20. }
  21. ]
  22. }
README.md · README · 265 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Outline Server
  2. > ## 📢 Official Outline MCP Server Available
  3. >
  4. > Outline now ships an **official MCP server** — we recommend using it.
  5. > [Read the docs](https://docs.getoutline.com/s/guide/doc/mcp-6j9jtENNKL).
  6. ---
  7. <!-- mcp-name: io.github.Vortiago/mcp-outline -->
  8. [![PyPI](https://img.shields.io/pypi/v/mcp-outline)](https://pypi.org/project/mcp-outline/)
  9. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  10. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
  11. [![CI](https://github.com/Vortiago/mcp-outline/actions/workflows/ci.yml/badge.svg)](https://github.com/Vortiago/mcp-outline/actions/workflows/ci.yml)
  12. [![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://github.com/Vortiago/mcp-outline/pkgs/container/mcp-outline)
  13. A Model Context Protocol server for interacting with Outline document management.
  14. ## Features
  15. - **Document operations**: Search, read, create, edit, archive documents
  16. - **Collections**: List, create, manage document hierarchies
  17. - **Comments**: Add and view threaded comments
  18. - **Backlinks**: Find documents referencing a specific document
  19. - **MCP Resources**: Direct content access via URIs (outline://document/{id}, outline://collection/{id}, etc.)
  20. - **Automatic rate limiting**: Transparent handling of API limits with retry logic
  21. ## Prerequisites
  22. Before using this MCP server, you need:
  23. - An [Outline](https://www.getoutline.com/) account (cloud hosted or self-hosted)
  24. - API key from Outline web UI: **Settings → API Keys → Create New**
  25. - Python 3.10+ (for non-Docker installations)
  26. > **Getting your API key**: Log into Outline → Click your profile → Settings → API Keys → "New API Key". Copy the generated token.
  27. ## Quick Start
  28. ### One-Click Install
  29. Click a button to install with interactive API key prompt:
  30. [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=mcp-outline&inputs=%5B%7B%22id%22%3A%22outline_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20OUTLINE_API_KEY%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22outline_api_url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Outline%20API%20URL%20(optional%2C%20for%20self-hosted)%22%2C%22password%22%3Afalse%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-outline%22%5D%2C%22env%22%3A%7B%22OUTLINE_API_KEY%22%3A%22%24%7Binput%3Aoutline_api_key%7D%22%2C%22OUTLINE_API_URL%22%3A%22%24%7Binput%3Aoutline_api_url%7D%22%7D%7D)
  31. [![Install in VS Code Insiders](https://img.shields.io/badge/Install_in-VS_Code_Insiders-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=mcp-outline&inputs=%5B%7B%22id%22%3A%22outline_api_key%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Enter%20OUTLINE_API_KEY%22%2C%22password%22%3Atrue%7D%2C%7B%22id%22%3A%22outline_api_url%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Outline%20API%20URL%20(optional%2C%20for%20self-hosted)%22%2C%22password%22%3Afalse%7D%5D&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22mcp-outline%22%5D%2C%22env%22%3A%7B%22OUTLINE_API_KEY%22%3A%22%24%7Binput%3Aoutline_api_key%7D%22%2C%22OUTLINE_API_URL%22%3A%22%24%7Binput%3Aoutline_api_url%7D%22%7D%7D&quality=insiders)
  32. [![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=mcp-outline&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJtY3Atb3V0bGluZSJdLCJlbnYiOnsiT1VUTElORV9BUElfS0VZIjoiJHtpbnB1dDpvdXRsaW5lX2FwaV9rZXl9IiwiT1VUTElORV9BUElfVVJMIjoiJHtpbnB1dDpvdXRsaW5lX2FwaV91cmx9In0sImlucHV0cyI6W3siaWQiOiJvdXRsaW5lX2FwaV9rZXkiLCJ0eXBlIjoicHJvbXB0U3RyaW5nIiwiZGVzY3JpcHRpb24iOiJFbnRlciBPVVRMSU5FX0FQSV9LRVkiLCJwYXNzd29yZCI6dHJ1ZX0seyJpZCI6Im91dGxpbmVfYXBpX3VybCIsInR5cGUiOiJwcm9tcHRTdHJpbmciLCJkZXNjcmlwdGlvbiI6Ik91dGxpbmUgQVBJIFVSTCAob3B0aW9uYWwsIGZvciBzZWxmLWhvc3RlZCkiLCJwYXNzd29yZCI6ZmFsc2V9XX0=)
  33. ### Manual Install
  34. Install with uv (recommended), pip, or Docker:
  35. ```bash
  36. uvx mcp-outline # using uv
  37. pip install mcp-outline # using pip
  38. ```
  39. ```bash
  40. # using Docker
  41. docker run -e OUTLINE_API_KEY=<your-key> ghcr.io/vortiago/mcp-outline:latest
  42. ```
  43. Then add to your MCP client config (works with VS Code, Claude Desktop, Cursor, and others):
  44. ```json
  45. {
  46. "inputs": [
  47. {
  48. "id": "outline_api_key",
  49. "type": "promptString",
  50. "description": "Enter OUTLINE_API_KEY",
  51. "password": true
  52. },
  53. {
  54. "id": "outline_api_url",
  55. "type": "promptString",
  56. "description": "Outline API URL (optional, for self-hosted)",
  57. "password": false
  58. }
  59. ],
  60. "servers": {
  61. "mcp-outline": {
  62. "command": "uvx",
  63. "args": ["mcp-outline"],
  64. "env": {
  65. "OUTLINE_API_KEY": "${input:outline_api_key}",
  66. "OUTLINE_API_URL": "${input:outline_api_url}"
  67. }
  68. }
  69. }
  70. }
  71. ```
  72. <details>
  73. <summary>Claude Code</summary>
  74. ```bash
  75. claude mcp add mcp-outline uvx mcp-outline
  76. ```
  77. Installing the repo as a plugin instead also bundles the
  78. `outline-explorer` agent (fast read-only wiki exploration) and the
  79. `outline` skill (Outline conventions: mermaidjs fences, document
  80. structure, editing workflows).
  81. </details>
  82. <details>
  83. <summary>Claude Desktop</summary>
  84. Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
  85. ```json
  86. {
  87. "mcpServers": {
  88. "mcp-outline": {
  89. "command": "uvx",
  90. "args": ["mcp-outline"],
  91. "env": {
  92. "OUTLINE_API_KEY": "<YOUR_API_KEY>",
  93. "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>"
  94. }
  95. }
  96. }
  97. }
  98. ```
  99. </details>
  100. Setup guides for more clients: [Docker (HTTP), Cline, Codex, Windsurf, and others](docs/client-setup.md)
  101. ## Configuration
  102. | Variable | Required | Default | Notes |
  103. |----------|----------|---------|-------|
  104. | `OUTLINE_API_KEY` | Yes* | - | Required for tool calls to succeed. For SSE/HTTP, can alternatively be provided per-request via `x-outline-api-key` header ([details](docs/configuration.md#per-user-outline-api-keys)) |
  105. | `OUTLINE_API_URL` | No | `https://app.getoutline.com/api` | For self-hosted: `https://your-domain/api` |
  106. | `OUTLINE_VERIFY_SSL` | No | `true` | Set `false` for self-signed certificates |
  107. | `OUTLINE_READ_ONLY` | No | `false` | `true` = disable ALL write operations ([details](docs/configuration.md#read-only-mode)) |
  108. | `OUTLINE_DISABLE_DELETE` | No | `false` | `true` = disable only delete operations ([details](docs/configuration.md#disable-delete-operations)) |
  109. | `OUTLINE_DISABLE_AI_TOOLS` | No | `false` | `true` = disable AI tools (for Outline instances without OpenAI) |
  110. | `OUTLINE_DISABLE_RECENT_DOCUMENTS` | No | `false` | `true` = disable the `list_recently_updated_documents` tool |
  111. | `OUTLINE_DYNAMIC_TOOL_LIST` | No | `false` | `true` = enable per-user tool filtering by role/key scopes ([details](docs/configuration.md#dynamic-tool-list)) |
  112. | `OUTLINE_MAX_CONNECTIONS` | No | `100` | Max concurrent connections in pool |
  113. | `OUTLINE_MAX_KEEPALIVE` | No | `20` | Max idle connections in pool |
  114. | `OUTLINE_TIMEOUT` | No | `30.0` | Read timeout in seconds |
  115. | `OUTLINE_CONNECT_TIMEOUT` | No | `5.0` | Connection timeout in seconds |
  116. | `OUTLINE_WRITE_TIMEOUT` | No | `30.0` | Write timeout in seconds |
  117. | `OUTLINE_CACHE_TTL` | No | `30` | Document cache TTL in seconds. The short default absorbs same-task read bursts without stressing the Outline API; set `0` to disable caching (always-fresh reads) or higher (e.g. `300`) for more API savings. Staged edits work either way |
  118. | `OUTLINE_CACHE_MAX_SIZE` | No | `100` | Max cached documents |
  119. | `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` (local), `sse` or `streamable-http` (remote) |
  120. | `MCP_HOST` | No | `127.0.0.1` | Server host. Use `0.0.0.0` in Docker for external connections |
  121. | `MCP_PORT` | No | `3000` | HTTP server port (only for `sse` and `streamable-http` modes) |
  122. ## Access Control
  123. | Feature | Env Var | Effect |
  124. |---------|---------|--------|
  125. | Read-only mode | `OUTLINE_READ_ONLY=true` | Disables all write operations — only search, read, and export tools available |
  126. | Disable deletes | `OUTLINE_DISABLE_DELETE=true` | Disables only delete operations, all other writes allowed |
  127. | Disable recent-changes tool | `OUTLINE_DISABLE_RECENT_DOCUMENTS=true` | Disables only the `list_recently_updated_documents` tool |
  128. | Dynamic tool list | `OUTLINE_DYNAMIC_TOOL_LIST=true` | Filters tools per-user based on Outline role and API key scopes |
  129. | Per-user Outline API keys | `x-outline-api-key` header | Each user passes their own Outline API key in HTTP mode for multi-user setups |
  130. Read-only mode takes precedence over disable-delete. See [Configuration Guide](docs/configuration.md) for details.
  131. ## Tools
  132. > **Note**: Tool availability depends on your [access control](#access-control) settings.
  133. ### Search & Discovery
  134. - `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
  135. - `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
  136. - `list_collections()` - List all collections
  137. - `get_collection_structure(collection_id)` - Get document hierarchy within a collection
  138. - `get_document_id_from_title(query, collection_id?)` - Find document ID by title search
  139. ### Document Reading
  140. - `read_document(document_id, offset?, limit?)` - Get document content with optional line-range pagination
  141. - `export_document(document_id)` - Export document as markdown
  142. ### Document Navigation
  143. - `get_document_toc(document_id)` - Get table of contents with heading structure and line numbers
  144. - `read_document_section(document_id, heading)` - Read a specific section by heading match (case-insensitive substring)
  145. ### Document Management
  146. - `create_document(title, collection_id, text?, parent_document_id?, publish?)` - Create new document
  147. - `update_document(document_id, title?, text?, append?)` - Replace full document content (append mode available)
  148. ### Document Editing
  149. - `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
  150. - `move_document(document_id, collection_id?, parent_document_id?)` - Move document to different collection or parent
  151. ### Document Lifecycle
  152. - `archive_document(document_id)` - Archive document
  153. - `unarchive_document(document_id)` - Restore document from archive
  154. - `delete_document(document_id, permanent?)` - Delete document (or move to trash)
  155. - `restore_document(document_id)` - Restore document from trash
  156. - `list_archived_documents()` - List all archived documents
  157. - `list_trash()` - List all documents in trash
  158. ### Comments & Collaboration
  159. - `add_comment(document_id, text, parent_comment_id?)` - Add comment to document (supports threaded replies)
  160. - `list_document_comments(document_id, include_anchor_text?, limit?, offset?)` - View document comments with pagination
  161. - `get_comment(comment_id, include_anchor_text?)` - Get specific comment details
  162. - `get_document_backlinks(document_id)` - Find documents that link to this document
  163. ### Collection Management
  164. - `create_collection(name, description?, color?)` - Create new collection
  165. - `update_collection(collection_id, name?, description?, color?)` - Update collection properties
  166. - `delete_collection(collection_id)` - Delete collection
  167. - `export_collection(collection_id, format?)` - Export collection (default: outline-markdown)
  168. - `export_all_collections(format?)` - Export all collections
  169. ### Batch Operations
  170. - `batch_create_documents(documents)` - Create multiple documents at once
  171. - `batch_update_documents(updates)` - Update multiple documents at once
  172. - `batch_move_documents(document_ids, collection_id?, parent_document_id?)` - Move multiple documents
  173. - `batch_archive_documents(document_ids)` - Archive multiple documents
  174. - `batch_delete_documents(document_ids, permanent?)` - Delete multiple documents
  175. ### AI-Powered
  176. - `ask_ai_about_documents(question, collection_id?, document_id?)` - Ask natural language questions about your documents
  177. ## Resources
  178. - `outline://collection/{id}` - Collection metadata (name, description, color, document count)
  179. - `outline://collection/{id}/tree` - Hierarchical document tree structure
  180. - `outline://collection/{id}/documents` - Flat list of documents in collection
  181. - `outline://document/{id}` - Full document content (markdown)
  182. - `outline://document/{id}/backlinks` - Documents that link to this document
  183. ## Development
  184. ```bash
  185. git clone https://github.com/Vortiago/mcp-outline.git
  186. cd mcp-outline
  187. uv sync --group dev
  188. uv run poe test-unit # unit tests
  189. uv run poe test-integration # integration tests (starts MCP server via stdio)
  190. uv run poe test-e2e # E2E tests (requires Docker)
  191. ```
  192. See [Development Guide](docs/development.md) for self-hosted Outline setup, MCP Inspector, and more.
  193. ## Troubleshooting
  194. **Server not connecting?** Test your API key:
  195. ```bash
  196. curl -H "Authorization: Bearer YOUR_API_KEY" YOUR_OUTLINE_URL/api/auth.info
  197. ```
  198. See [Troubleshooting Guide](docs/troubleshooting.md) for common issues with tools, rate limiting, and Docker.
  199. ## Contributing
  200. Contributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions.
  201. ## License
  202. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  203. ## Acknowledgments
  204. - Built with [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
  205. - Uses [Outline API](https://getoutline.com) for document management

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.