outline-mcp

Outline 用の読み取り専用 MCP サーバーです。エージェントに Wiki への検索・読み取りアクセスを提供します。設計上、書き込みは一切行いません。

なぜ作ったか

Outline の API はフラットな RPC サーフェスです。すべてのエンドポイントは POST {base}/api/<method> で、JSON ボディと Bearer トークンを使用します。この均一性により、有用な MCP サーバーは単一のリクエスト関数と厳選されたツールリストで実現できます。このパッケージは意図的に小さく保たれています。MCP SDK と zod 以外のランタイム依存はなく、エージェントが適切なツールを選択するかどうかを左右するツールの説明と出力整形を完全に制御できます。

サーバーは読み取り専用です。コード内に作成・更新・移動・アーカイブのパスは一切ありません。

Related MCP server: outline-mcp

ツール

get_document は完全な URL、素の urlId、または UUID を受け付けます。urlId は [A-Za-z0-9]{10,15} です。有効な ID サフィックスがないスラッグはローカルで拒否されます。API がそれに対して 400 validation_error を返すためです。

要件

• Node 18 以降（組み込みの fetch を使用。ネイティブ依存はありません）。

• Outline インスタンス（セルフホストまたは Outline.com）。

はじめに

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

API キーを取得する

Outline で: Settings → API & Apps → New API key。値は ol_api_ で始まり、その後に 38 文字の英数字が続きます。

2 つの環境変数を設定する

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

設定

サーバーは正確に 2 つの環境変数を読み取ります:

Claude Code — mcp.json（プロジェクト）または .mcp.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_…"
      }
    }
  }
}

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_…"
      }
    }
  }
}

注: Claude Desktop はこのファイル内の ${VAR} 参照を展開しません。キーを文字通り貼り付けてください。"${OUTLINE_API_KEY}" と書かないでください。

その他の MCP クライアント（Zed、Cline、または MCP stdio プロトコルを話すもの）— 同じ形です。node /path/to/outline-mcp/index.js を 2 つの変数を環境に設定して起動します。

仕組み

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

サーバーは起動時に資格情報を検証しません。起動時に終了するサーバーは、クライアントに「接続に失敗しました」と表示され、説明がありません。代わりに、起動してツールをリストし、各呼び出しは欠落している変数を示すメッセージを返します。

開発

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 は、ライブインスタンスを指す OUTLINE_API_URL と OUTLINE_API_KEY を必要とします。これらがない場合は「smoke skipped」という行を出力して終了コード 0 で終了します。ツールの追加方法については CONTRIBUTING.md を参照してください。

制限事項

• 設計上、読み取り専用です。 作成、更新、移動、アーカイブ、コメント書き込みはありません。

• 添付ファイルは解決されません。 埋め込まれた画像やファイルは、マークダウン内で /api/attachments.redirect?id=… リンクのまま残ります。テキストを読むエージェントには読み込まれません。

• プロアクティブなレート制限シグナルはありません。 インスタンスは RateLimit-* ヘッダーを返しません。429 の場合、クライアントは Retry-After（最大 10 秒）を尊重し、正確に 1 回再試行してから失敗を報告します。

• 長いドキュメントは maxChars（デフォルト 40,000）で切り詰められ、実際の全長を示すマーカーが付けられます。

セキュリティ

API キーは送信リクエストの Authorization ヘッダーでのみ送信されます。クライアントから出るエラーメッセージはすべて、キーを ol_api_*** に置き換えるリダクションステップを通過します。また、キーの経路（stdio トランスポートや stderr ログ）でキー自体が出力されることはありません。Outline インスタンスがスコープ付きキーをサポートしている場合は、このサーバーには読み取り専用スコープのキーを使用することをお勧めします。

ライセンス

MIT — 全文は LICENSE を参照してください。