outline-mcp

Nur-Lese-MCP-Server für Outline. Bietet einem Agenten Such- und Lesezugriff auf dein Wiki – keine Schreibvorgänge, bewusst.

Warum

Die API von Outline ist eine flache RPC-Oberfläche – jeder Endpunkt ist POST {base}/api/<method> mit einem JSON-Body und einem Bearer-Token. Diese Einheitlichkeit bedeutet, dass ein nützlicher MCP-Server aus einer einzigen Request-Funktion plus einer kuratierten Tool-Liste besteht. Dieses Paket ist bewusst klein: keine Laufzeitabhängigkeit außer dem MCP-SDK und zod, und volle Kontrolle über die Tool-Beschreibungen und die Ausgabeformatierung, die darüber entscheiden, ob der Agent das richtige Tool auswählt.

Der Server ist nur lesend: Es gibt keinen Create-, Update-, Move- oder Archiv-Pfad im gesamten Code.

Related MCP server: outline-mcp

Tools

get_document akzeptiert eine vollständige URL, eine nackte urlId oder eine UUID. Eine urlId ist [A-Za-z0-9]{10,15} – ein Slug ohne gültiges ID-Suffix wird lokal abgelehnt, weil die API mit 400 validation_error antwortet.

Voraussetzungen

• Node 18 oder neuer (verwendet das eingebaute fetch; keine nativen Abhängigkeiten).

• Eine Outline-Instanz – selbst gehostet oder Outline.com.

Erste Schritte

git clone https://github.com/minhquan2904/outline-mcp.git
cd outline-mcp
npm ci

API-Schlüssel erhalten

In Outline: Einstellungen → API & Apps → Neuer API-Schlüssel. Der Wert beginnt mit ol_api_ gefolgt von 38 alphanumerischen Zeichen.

Die zwei Umgebungsvariablen setzen

export OUTLINE_API_URL=https://your-outline-instance
export OUTLINE_API_KEY=ol_api_…
node index.js

Konfiguration

Der Server liest genau zwei Umgebungsvariablen:

Claude Code – mcp.json (Projekt) oder .mcp.json (Benutzer):

{
  "mcpServers": {
    "outline": {
      "command": "node",
      "args": ["/path/to/outline-mcp/index.js"],
      "env": {
        "OUTLINE_API_URL": "https://your-outline-instance",
        "OUTLINE_API_KEY": "ol_api_…"
      }
    }
  }
}

Claude Desktop – claude_desktop_config.json:

{
  "mcpServers": {
    "outline": {
      "command": "node",
      "args": ["/path/to/outline-mcp/index.js"],
      "env": {
        "OUTLINE_API_URL": "https://your-outline-instance",
        "OUTLINE_API_KEY": "ol_api_…"
      }
    }
  }
}

Hinweis: Claude Desktop expandiert keine ${VAR}-Referenzen in dieser Datei – füge den Schlüssel wörtlich ein, schreibe nicht "${OUTLINE_API_KEY}".

Jeder andere MCP-Client (Zed, Cline oder alles, was das MCP-stdio-Protokoll spricht) – gleiche Form: starte node /path/to/outline-mcp/index.js mit den beiden Variablen in seiner Umgebung.

So funktioniert es

flowchart LR
    CC[Claude Code / any MCP client]
    OM[outline-mcp<br/>Node 18+, stdio server]
    O[Outline instance]
    F[format.js<br/>parse ref · truncate · render]
    C[client.js<br/>timeout · error map · 429 retry]

    CC -->|stdio| OM
    OM -->|"POST /api/{method} · Bearer ol_api_…"| O
    OM -.-> F
    OM -.-> C

Der Server validiert Anmeldedaten nie beim Start. Ein Server, der beim Booten beendet wird, erscheint im Client als „Verbindung fehlgeschlagen“ ohne Erklärung; stattdessen startet er, listet seine Tools auf, und jeder Aufruf gibt eine Meldung zurück, die die fehlende Variable benennt.

Entwicklung

npm ci
npm test          # unit tests, fully offline (fetch is stubbed)
npm run smoke     # every tool against a real instance; no-ops without credentials

npm run smoke erfordert OUTLINE_API_URL + OUTLINE_API_KEY, die auf eine Live-Instanz zeigen; ohne sie gibt es eine Zeile „smoke skipped“ aus und beendet sich mit 0. Siehe CONTRIBUTING.md für Hinweise zum Hinzufügen eines Tools.

Einschränkungen

• Nur-Lese-Design. Keine Create-, Update-, Move-, Archiv- oder Kommentar-Schreibvorgänge.

• Anhänge werden nicht aufgelöst. Eingebettete Bilder und Dateien bleiben als /api/attachments.redirect?id=…-Links im Markdown; sie werden für einen Agenten, der den Text liest, nicht geladen.

• Kein proaktives Rate-Limit-Signal. Die Instanz gibt keine RateLimit-*-Header zurück. Bei einem 429 beachtet der Client Retry-After (auf 10s begrenzt) und versucht es genau einmal erneut, dann meldet er den Fehler.

• Lange Dokumente werden bei maxChars (Standard 40 000) abgeschnitten, mit einem Marker, der die tatsächliche Gesamtlänge angibt.

Sicherheit

Der API-Schlüssel reist nur im Authorization-Header ausgehender Anfragen. Jede Fehlermeldung, die den Client verlässt, durchläuft einen Schwärzungsschritt, der den Schlüssel durch ol_api_*** ersetzt, und nichts auf dem Pfad des Schlüssels (der stdio-Transport oder das stderr-Log) gibt jemals den Schlüssel selbst aus. Wenn deine Outline-Instanz bereichsbezogene Schlüssel unterstützt, bevorzuge einen nur-lesenden Schlüssel für diesen Server.

Lizenz

MIT – siehe LICENSE für den vollständigen Text.