{ "markdown": "# MCP Outline Server\n\n> ## 📢 Official Outline MCP Server Available\n>\n> Outline now ships an **official MCP server** — we recommend using it.\n> [Read the docs](https://docs.getoutline.com/s/guide/doc/mcp-6j9jtENNKL).\n\n---\n\n\n\n[![PyPI](https://img.shields.io/pypi/v/mcp-outline)](https://pypi.org/project/mcp-outline/)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![CI](https://github.com/Vortiago/mcp-outline/actions/workflows/ci.yml/badge.svg)](https://github.com/Vortiago/mcp-outline/actions/workflows/ci.yml)\n[![Docker](https://img.shields.io/badge/docker-ghcr.io-blue)](https://github.com/Vortiago/mcp-outline/pkgs/container/mcp-outline)\n\nA Model Context Protocol server for interacting with Outline document management.\n\n## Features\n\n- **Document operations**: Search, read, create, edit, archive documents\n- **Collections**: List, create, manage document hierarchies\n- **Comments**: Add and view threaded comments\n- **Backlinks**: Find documents referencing a specific document\n- **MCP Resources**: Direct content access via URIs (outline://document/{id}, outline://collection/{id}, etc.)\n- **Automatic rate limiting**: Transparent handling of API limits with retry logic\n\n## Prerequisites\n\nBefore using this MCP server, you need:\n\n- An [Outline](https://www.getoutline.com/) account (cloud hosted or self-hosted)\n- API key from Outline web UI: **Settings → API Keys → Create New**\n- Python 3.10+ (for non-Docker installations)\n\n> **Getting your API key**: Log into Outline → Click your profile → Settings → API Keys → \"New API Key\". Copy the generated token.\n\n## Quick Start\n\n### One-Click Install\n\nClick a button to install with interactive API key prompt:\n\n[![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)\n[![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)\n[![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=)\n\n### Manual Install\n\nInstall with uv (recommended), pip, or Docker:\n\n```bash\nuvx mcp-outline # using uv\npip install mcp-outline # using pip\n```\n\n```bash\n# using Docker\ndocker run -e OUTLINE_API_KEY= ghcr.io/vortiago/mcp-outline:latest\n```\n\nThen add to your MCP client config (works with VS Code, Claude Desktop, Cursor, and others):\n\n```json\n{\n \"inputs\": [\n {\n \"id\": \"outline_api_key\",\n \"type\": \"promptString\",\n \"description\": \"Enter OUTLINE_API_KEY\",\n \"password\": true\n },\n {\n \"id\": \"outline_api_url\",\n \"type\": \"promptString\",\n \"description\": \"Outline API URL (optional, for self-hosted)\",\n \"password\": false\n }\n ],\n \"servers\": {\n \"mcp-outline\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-outline\"],\n \"env\": {\n \"OUTLINE_API_KEY\": \"${input:outline_api_key}\",\n \"OUTLINE_API_URL\": \"${input:outline_api_url}\"\n }\n }\n }\n}\n```\n\n
\nClaude Code\n\n```bash\nclaude mcp add mcp-outline uvx mcp-outline\n```\n\nInstalling the repo as a plugin instead also bundles the\n`outline-explorer` agent (fast read-only wiki exploration) and the\n`outline` skill (Outline conventions: mermaidjs fences, document\nstructure, editing workflows).\n
\n\n
\nClaude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"mcp-outline\": {\n \"command\": \"uvx\",\n \"args\": [\"mcp-outline\"],\n \"env\": {\n \"OUTLINE_API_KEY\": \"\",\n \"OUTLINE_API_URL\": \"\"\n }\n }\n }\n}\n```\n
\n\nSetup guides for more clients: [Docker (HTTP), Cline, Codex, Windsurf, and others](docs/client-setup.md)\n\n## Configuration\n\n| Variable | Required | Default | Notes |\n|----------|----------|---------|-------|\n| `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)) |\n| `OUTLINE_API_URL` | No | `https://app.getoutline.com/api` | For self-hosted: `https://your-domain/api` |\n| `OUTLINE_VERIFY_SSL` | No | `true` | Set `false` for self-signed certificates |\n| `OUTLINE_READ_ONLY` | No | `false` | `true` = disable ALL write operations ([details](docs/configuration.md#read-only-mode)) |\n| `OUTLINE_DISABLE_DELETE` | No | `false` | `true` = disable only delete operations ([details](docs/configuration.md#disable-delete-operations)) |\n| `OUTLINE_DISABLE_AI_TOOLS` | No | `false` | `true` = disable AI tools (for Outline instances without OpenAI) |\n| `OUTLINE_DISABLE_RECENT_DOCUMENTS` | No | `false` | `true` = disable the `list_recently_updated_documents` tool |\n| `OUTLINE_DYNAMIC_TOOL_LIST` | No | `false` | `true` = enable per-user tool filtering by role/key scopes ([details](docs/configuration.md#dynamic-tool-list)) |\n| `OUTLINE_MAX_CONNECTIONS` | No | `100` | Max concurrent connections in pool |\n| `OUTLINE_MAX_KEEPALIVE` | No | `20` | Max idle connections in pool |\n| `OUTLINE_TIMEOUT` | No | `30.0` | Read timeout in seconds |\n| `OUTLINE_CONNECT_TIMEOUT` | No | `5.0` | Connection timeout in seconds |\n| `OUTLINE_WRITE_TIMEOUT` | No | `30.0` | Write timeout in seconds |\n| `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 |\n| `OUTLINE_CACHE_MAX_SIZE` | No | `100` | Max cached documents |\n| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` (local), `sse` or `streamable-http` (remote) |\n| `MCP_HOST` | No | `127.0.0.1` | Server host. Use `0.0.0.0` in Docker for external connections |\n| `MCP_PORT` | No | `3000` | HTTP server port (only for `sse` and `streamable-http` modes) |\n\n## Access Control\n\n| Feature | Env Var | Effect |\n|---------|---------|--------|\n| Read-only mode | `OUTLINE_READ_ONLY=true` | Disables all write operations — only search, read, and export tools available |\n| Disable deletes | `OUTLINE_DISABLE_DELETE=true` | Disables only delete operations, all other writes allowed |\n| Disable recent-changes tool | `OUTLINE_DISABLE_RECENT_DOCUMENTS=true` | Disables only the `list_recently_updated_documents` tool |\n| Dynamic tool list | `OUTLINE_DYNAMIC_TOOL_LIST=true` | Filters tools per-user based on Outline role and API key scopes |\n| 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 |\n\nRead-only mode takes precedence over disable-delete. See [Configuration Guide](docs/configuration.md) for details.\n\n## Tools\n\n> **Note**: Tool availability depends on your [access control](#access-control) settings.\n\n### Search & Discovery\n- `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\n- `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\n- `list_collections()` - List all collections\n- `get_collection_structure(collection_id)` - Get document hierarchy within a collection\n- `get_document_id_from_title(query, collection_id?)` - Find document ID by title search\n\n### Document Reading\n- `read_document(document_id, offset?, limit?)` - Get document content with optional line-range pagination\n- `export_document(document_id)` - Export document as markdown\n\n### Document Navigation\n- `get_document_toc(document_id)` - Get table of contents with heading structure and line numbers\n- `read_document_section(document_id, heading)` - Read a specific section by heading match (case-insensitive substring)\n\n### Document Management\n- `create_document(title, collection_id, text?, parent_document_id?, publish?)` - Create new document\n- `update_document(document_id, title?, text?, append?)` - Replace full document content (append mode available)\n\n### Document Editing\n- `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\n- `move_document(document_id, collection_id?, parent_document_id?)` - Move document to different collection or parent\n\n### Document Lifecycle\n- `archive_document(document_id)` - Archive document\n- `unarchive_document(document_id)` - Restore document from archive\n- `delete_document(document_id, permanent?)` - Delete document (or move to trash)\n- `restore_document(document_id)` - Restore document from trash\n- `list_archived_documents()` - List all archived documents\n- `list_trash()` - List all documents in trash\n\n### Comments & Collaboration\n- `add_comment(document_id, text, parent_comment_id?)` - Add comment to document (supports threaded replies)\n- `list_document_comments(document_id, include_anchor_text?, limit?, offset?)` - View document comments with pagination\n- `get_comment(comment_id, include_anchor_text?)` - Get specific comment details\n- `get_document_backlinks(document_id)` - Find documents that link to this document\n\n### Collection Management\n- `create_collection(name, description?, color?)` - Create new collection\n- `update_collection(collection_id, name?, description?, color?)` - Update collection properties\n- `delete_collection(collection_id)` - Delete collection\n- `export_collection(collection_id, format?)` - Export collection (default: outline-markdown)\n- `export_all_collections(format?)` - Export all collections\n\n### Batch Operations\n- `batch_create_documents(documents)` - Create multiple documents at once\n- `batch_update_documents(updates)` - Update multiple documents at once\n- `batch_move_documents(document_ids, collection_id?, parent_document_id?)` - Move multiple documents\n- `batch_archive_documents(document_ids)` - Archive multiple documents\n- `batch_delete_documents(document_ids, permanent?)` - Delete multiple documents\n\n### AI-Powered\n- `ask_ai_about_documents(question, collection_id?, document_id?)` - Ask natural language questions about your documents\n\n## Resources\n\n- `outline://collection/{id}` - Collection metadata (name, description, color, document count)\n- `outline://collection/{id}/tree` - Hierarchical document tree structure\n- `outline://collection/{id}/documents` - Flat list of documents in collection\n- `outline://document/{id}` - Full document content (markdown)\n- `outline://document/{id}/backlinks` - Documents that link to this document\n\n## Development\n\n```bash\ngit clone https://github.com/Vortiago/mcp-outline.git\ncd mcp-outline\nuv sync --group dev\n\nuv run poe test-unit # unit tests\nuv run poe test-integration # integration tests (starts MCP server via stdio)\nuv run poe test-e2e # E2E tests (requires Docker)\n```\n\nSee [Development Guide](docs/development.md) for self-hosted Outline setup, MCP Inspector, and more.\n\n## Troubleshooting\n\n**Server not connecting?** Test your API key:\n```bash\ncurl -H \"Authorization: Bearer YOUR_API_KEY\" YOUR_OUTLINE_URL/api/auth.info\n```\n\nSee [Troubleshooting Guide](docs/troubleshooting.md) for common issues with tools, rate limiting, and Docker.\n\n## Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Built with [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)\n- Uses [Outline API](https://getoutline.com) for document management\n", "bytes": 13978, "sha": "5443966da8c81b346e3ebdc4b231793f74b05d191880e8d4ddf8b7ad09c8002e", "repo_slug": "vortiago/mcp-outline", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/plg_vortiago_mcp_outline_mcp_outline_675fbd11/readme" }