Outline MCP

intent

use this skill to bridge your outline workspace into an ai agent's context via model context protocol (mcp). the skill lets agents search documents, read markdown, create and edit pages, manage collections, add comments, and bulk upload images. run this when you want ai to reason over or modify your outline docs in real-time, or when you need to push local files into outline at scale.

inputs

environment variables (required):

• OUTLINE_API_KEY: API key generated from your outline workspace settings > AI tab. Single-use during generation, store securely. expires if workspace member loses access.
• OUTLINE_URL: Your outline workspace MCP endpoint. typically https://your-workspace.getoutline.com/mcp. verify the /mcp path exists and MCP is toggled "on" in outline settings > AI.

local system requirements:

• node.js v18 or higher installed and in PATH.
• npm available to install @modelcontextprotocol/sdk.
• filesystem read permissions for any file paths you pass to upload or bulk-sync tools (runs as the user executing the process).

outline workspace setup (one-time):

1. enable AI features in outline workspace settings > AI tab.
2. toggle MCP switch to "on".
3. click "generate API key" and copy immediately (only shown once).
4. confirm your workspace URL is accessible and has the /mcp endpoint.

external connection: outline api (mcp endpoint).

• transport: streamable HTTP over SSE (server-sent events).
• auth: bearer token in authorization: bearer <OUTLINE_API_KEY> header.
• rate limits: not publicly documented by outline. expect standard api throttling. retry with exponential backoff if you hit 429 (too many requests).
• availability: depends on outline workspace uptime and network connectivity from your host.

procedure

1. install dependencies. run npm install in the skill directory. this fetches @modelcontextprotocol/sdk and other node modules required by mcp_bridge.mjs and bulk_sync.mjs.

   • input: skill directory, npm in PATH.
   • output: node_modules/ directory created, package-lock.json written.

2. set environment variables. export or configure OUTLINE_API_KEY and OUTLINE_URL in your openclaw process environment. verify they are accessible to the node process that will run the scripts.

   • input: API key and MCP URL from outline workspace.
   • output: environment variables available to child processes.

3. call mcp_bridge.mjs with a tool name and json arguments. syntax: node scripts/mcp_bridge.mjs call "<tool_name>" '<json_args>'.

   • input: tool name (string), json object with required/optional parameters.
   • output: json response from outline API, piped through mcp protocol.

4. for document search/list: call list_documents with optional query, collectionId, offset, limit. if query is empty, returns recent documents.

   • input: query (optional string), collectionId (optional string), offset/limit (optional integers, limit max 100).
   • output: array of document objects with id, title, collectionId, updatedAt, createdBy.

5. for document read: call read_document with id. retrieves full markdown content from outline.

   • input: id (required string, document uuid).
   • output: markdown string of document body.

6. for document create: call create_document with title, optional text, required collectionId or parentDocumentId, optional icon/color, optional publish flag (default true).

   • input: title (string), text (optional markdown), collectionId (string if parentDocumentId absent), parentDocumentId (string if collectionId absent), icon (optional emoji), color (optional hex), publish (optional boolean).
   • output: new document object with id, url, createdAt.

7. for document edit: call update_document with id, optional title/text, optional editMode (replace/append/prepend, default replace), optional collectionId (required if publishing draft with no collection), optional icon/color, optional publish flag.

   • input: id (string), title/text (optional strings), editMode (optional enum), collectionId (conditional string), icon/color (optional string/null), publish (optional boolean).
   • output: updated document object.

8. for document move: call move_document with id, optional collectionId or parentDocumentId, optional index (zero-based position among siblings).

   • input: id (string), collectionId (optional string), parentDocumentId (optional string), index (optional integer).
   • output: document object with updated location metadata.

9. for collection list: call list_collections with optional query, offset, limit.

   • input: query (optional string), offset/limit (optional integers).
   • output: array of collection objects with id, name, icon, color, documentCount.

10. for collection create: call create_collection with name, optional description, icon, color.

    • input: name (required string), description (optional markdown), icon (optional emoji), color (optional hex).
    • output: new collection object with id, url.

11. for collection update: call update_collection with id, optional name, description, icon, color.

    • input: id (required string), name/description (optional strings), icon/color (optional string/null).
    • output: updated collection object.

12. for comment list: call list_comments with optional documentId or collectionId, optional parentCommentId, optional statusFilter (array of resolved/unresolved), optional offset, limit.

    • input: documentId (optional string), collectionId (optional string), parentCommentId (optional string), statusFilter (optional array), offset/limit (optional integers).
    • output: array of comment objects with id, text, status, createdBy, createdAt.

13. for comment create: call create_comment with required documentId, required text, optional parentCommentId (for replies).

    • input: documentId (required string), text (required markdown), parentCommentId (optional string).
    • output: new comment object with id, url, createdAt.

14. for comment update: call update_comment with id, optional text, optional status (resolved/unresolved).

    • input: id (required string), text (optional markdown), status (optional enum).
    • output: updated comment object.

15. for comment delete: call delete_comment with id.

    • input: id (required string).
    • output: confirmation object (http 204 on success, or error json).

16. for user directory list: call list_users with optional query, role (admin/member/viewer/guest), filter (active/suspended/invited/all), offset, limit.

    • input: query (optional string), role (optional enum), filter (optional enum), offset/limit (optional integers).
    • output: array of user objects with id, name, email, role, status.

17. for bulk file upload and document update (advanced): call bulk_sync.mjs with syntax: node scripts/bulk_sync.mjs bulk-sync "<doc_id>" "<comma-separated-file-paths>" "<template_text>" "<edit_mode>". the script uploads each file to outline, captures media urls, substitutes {{MEDIA}} placeholder in template_text, then updates the document using the specified edit mode.

    • input: doc_id (string), file paths (comma-separated absolute paths, string), template_text (markdown with optional {{MEDIA}} placeholder), edit_mode (replace/append/prepend).
    • output: updated document object with media urls embedded in markdown.

decision points

if outline MCP is not enabled in workspace settings: the API will return 401 unauthorized or MCP endpoint will not exist. verify settings > AI tab has MCP toggled "on" before attempting any tool calls.

if API key is missing, invalid, or expired: outline will respond with 401 unauthorized. regenerate a new API key in settings > AI tab and update OUTLINE_API_KEY env var.

if OUTLINE_URL is malformed or the workspace is unreachable: the http connection will time out or fail with a network error. verify the URL includes the /mcp path and the workspace is online.

if a document query returns empty results: the list_documents tool will return an empty array. either refine the search query, check the collectionId filter, or create the document first.

if you want to add content without rewriting the entire document: use update_document with editMode: "append" or editMode: "prepend" instead of the default replace. this preserves existing content and is more token-efficient.

if you need to upload multiple images and update a document in one call: use the bulk_sync.mjs script instead of separate upload and update calls. it batches the operations and reduces round-trips.

if file paths passed to upload or bulk_sync do not exist or are not readable: the script will throw a filesystem error. verify absolute paths are correct and the process user has read permission on those files.

if outline rate-limits your requests (429 response): back off exponentially (e.g., 1s, 2s, 4s) and retry. the skill does not implement automatic retry logic, so the calling agent must handle this.

if a comment is created on a document and later the document is deleted: the comment orphan behavior depends on outline's data model. verify the document exists before adding comments.

if you attempt to move a document to a collection it already belongs to: outline will still accept the move and may not change the document's state. confirm the target collectionId is different.

if publishing a draft document without providing a collectionId: the API requires either collectionId or it must already have one set. provide collectionId when publishing a draft for the first time.

output contract

tool responses are json objects. each tool returns a json object conforming to outline's api schema. specific contracts:

• list_documents: array of document objects. each has id (string), title (string), collectionId (string), updatedAt (iso8601), createdBy (user object).
• read_document: markdown string (the full document body).
• create_document: document object with id, url, createdAt, title, collectionId.
• update_document: updated document object with same fields as create response.
• move_document: document object with updated parentDocumentId and/or collectionId.
• list_collections: array of collection objects with id, name, icon, color, documentCount.
• create_collection: collection object with id, url, createdAt.
• update_collection: updated collection object.
• list_comments: array of comment objects with id, text, status (resolved/unresolved), createdBy, createdAt.
• create_comment: comment object with id, url, createdAt, documentId.
• update_comment: updated comment object.
• delete_comment: http 204 no content on success, or error json on failure.
• list_users: array of user objects with id, name, email, role (admin/member/viewer/guest), status (active/suspended/invited).
• bulk_sync: updated document object with markdown body containing resolved media urls (placeholders replaced with actual image links).

errors: on api failure, tools return http error codes (401, 404, 429, 500) with json error body. the calling process should parse and handle these.

file locations: uploaded media from bulk_sync is stored in outline's cdn/attachment service. the returned document markdown will contain outline-generated urls pointing to these assets.

outcome signal

• after calling list_documents: you receive an array of documents matching your query. verify the count, titles, and collectionIds match what you see in the outline ui.
• after calling read_document: you get markdown text matching the outline document preview. copy a section and verify it matches the ui to confirm freshness.
• after calling create_document: the new document appears in the outline ui under the specified collection or parent. refresh the browser if needed.
• after calling update_document: the document content updates in outline. open it in the ui and verify the new text, icon, or color is visible.
• after calling move_document: the document relocates to the new collection/parent in the outline sidebar and search results.
• after calling create_collection: a new collection appears in the outline left sidebar and is selectable when creating documents.
• after calling list_comments or create_comment: comments appear in the outline document comments panel. if you created a comment, refresh the ui to see it.
• after calling list_users: you see a list of workspace members. filter by role or status and verify counts match your workspace member list.
• after calling bulk_sync: the target document updates with the markdown template and embedded image urls. open the document in outline and verify images render and links are valid.
• if a tool call fails: check the http error code and error message. 401 usually means auth issue, 404 means id not found, 429 means rate limited. retry or fix the input and try again.

credits: original skill authored by tinker. enriched per implexa standards with explicit decision points, edge case handling, and detailed input/output contracts.