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 后缀的 slug 会在本地被拒绝，因为 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 中：设置 → API 与应用 → 新建 API 密钥。该值以 ol_api_ 开头，后跟 38 个字母数字字符。

设置两个环境变量

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

配置

服务器只读取两个环境变量：

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。

工作原理

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 了解如何添加工具。

限制

• 按设计只读。 不支持创建、更新、移动、归档或评论写入。

• 附件不会被解析。 嵌入的图片和文件在 markdown 中保持为 /api/attachments.redirect?id=… 链接；读取文本的智能体无法加载它们。

• 没有主动的速率限制信号。 实例不会返回 RateLimit-* 头。遇到 429 时，客户端会遵循 Retry-After（上限 10 秒）并恰好重试一次，然后报告失败。

• 长文档会在 maxChars（默认 40 000）处截断，并带有一个标记说明真实总长度。

安全

API 密钥只出现在出站请求的 Authorization 头中。任何离开客户端的错误消息都会经过脱敏步骤，将密钥替换为 ol_api_***，并且密钥路径上的任何内容（stdio 传输或 stderr 日志）都不会打印密钥本身。如果你的 Outline 实例支持作用域密钥，请为此服务器优先使用只读作用域的密钥。

许可证

MIT——完整文本见 LICENSE。