MCP-轮廓服务器

Name: MCP-轮廓服务器
Author: Vortiago

作者：Vortiago54 星标更新：2025-11-23

安装使用来源：spider==github.com

项目介绍

MCP Outline Server

这是一个用于与Outline文档管理系统交互的Model Context Protocol服务器。

功能

文档操作：搜索、阅读、创建、编辑、归档文档
集合：列出、创建、管理文档层次结构
评论：添加和查看线程评论
反向链接：查找引用特定文档的文档
MCP资源：通过URI（如：outline://document/{id}，outline://collection/{id}等）直接访问内容
自动速率限制：透明处理API限制并带有重试逻辑

先决条件

在使用此MCP服务器之前，你需要：

一个Outline账户（云托管或自托管）
从Outline Web UI获取API密钥：设置 → API密钥 → 创建新密钥
Python 3.10+（非Docker安装）

获取你的API密钥：登录Outline → 点击你的个人资料 → 设置 → API密钥 → “新建API密钥”。复制生成的令牌。

安装

使用uv（推荐）

uvx mcp-outline

使用pip

pip install mcp-outline

使用Docker

docker run -e OUTLINE_API_KEY=<your-key> ghcr.io/vortiago/mcp-outline:latest

或者从源码构建：

docker buildx build -t mcp-outline .
docker run -e OUTLINE_API_KEY=<your-key> mcp-outline

配置

变量	必需	默认值	备注
`OUTLINE_API_KEY`	是	-	从Outline Web UI获取：设置 → API密钥 → 创建新密钥
`OUTLINE_API_URL`	否	`https://app.getoutline.com/api`	对于自托管：`https://your-domain/api`
`OUTLINE_READ_ONLY`	否	`false`	`true` = 禁用所有写入操作（详情见#只读模式）
`OUTLINE_DISABLE_DELETE`	否	`false`	`true` = 仅禁用删除操作（详情见#禁用删除操作）
`OUTLINE_DISABLE_AI_TOOLS`	否	`false`	`true` = 禁用AI工具（对于没有OpenAI的Outline实例）
`MCP_TRANSPORT`	否	`stdio`	传输模式：`stdio`（本地），`sse` 或 `streamable-http`（远程）
`MCP_HOST`	否	`127.0.0.1`	服务器主机。在Docker中使用`0.0.0.0`以允许外部连接
`MCP_PORT`	否	`3000`	HTTP服务器端口（仅适用于`sse`和`streamable-http`模式）

访问控制

配置服务器权限以控制允许的操作：

只读模式

设置 OUTLINE_READ_ONLY=true 以启用仅查看访问。只有搜索、阅读、导出和协作查看工具可用。所有写入操作（创建、更新、移动、归档、删除）都将被禁用。

使用场景：

团队成员共享访问，只能查看内容
安全集成AI助手，不应修改文档
公共或演示实例，应保护内容

可用工具：

搜索与发现：search_documents，list_collections，get_collection_structure，get_document_id_from_title
文档阅读：read_document，export_document
评论：list_document_comments，get_comment
协作：get_document_backlinks
集合：export_collection，export_all_collections
AI：ask_ai_about_documents（如果未通过OUTLINE_DISABLE_AI_TOOLS禁用）

禁用删除操作

设置 OUTLINE_DISABLE_DELETE=true 以允许创建和更新工作流，同时防止意外数据丢失。仅禁用删除操作。

使用场景：

生产环境，不应删除文档
防止意外删除
安全的内容编辑工作流

禁用工具：

delete_document，delete_collection
batch_delete_documents

重要：OUTLINE_READ_ONLY=true优先于OUTLINE_DISABLE_DELETE。如果两者都设置，服务器将以只读模式运行。

添加到您的客户端

先决条件：使用pip install uv或从astral.sh/uv安装uv

<details> <summary>添加到Claude Desktop</summary>

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（或Windows上的%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "mcp-outline": {
      "command": "uvx",
      "args": ["mcp-outline"],
      "env": {
        "OUTLINE_API_KEY": "<YOUR_API_KEY>",
        "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // 可选
      }
    }
  }
}

</details> <details> <summary>添加到Cursor</summary>

转到设置 → MCP 并点击添加服务器：

{
  "mcp-outline": {
    "command": "uvx",
    "args": ["mcp-outline"],
    "env": {
      "OUTLINE_API_KEY": "<YOUR_API_KEY>",
      "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // 可选
    }
  }
}

</details> <details> <summary>添加到VS Code</summary>

在您的工作区创建一个.vscode/mcp.json文件，并使用以下配置：

{
  "servers": {
    "mcp-outline": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-outline"],
      "env": {
        "OUTLINE_API_KEY": "<YOUR_API_KEY>"
      }
    }
  }
}

对于自托管的Outline实例，向env对象添加OUTLINE_API_URL。

可选：使用输入变量来存储敏感凭证：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "outline-api-key",
      "description": "Outline API Key",
      "password": true
    }
  ],
  "servers": {
    "mcp-outline": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-outline"],
      "env": {
        "OUTLINE_API_KEY": "${input:outline-api-key}"
      }
    }
  }
}

VS Code会自动发现并加载此配置文件中的MCP服务器。更多细节，请参阅官方VS Code MCP文档。

</details> <details> <summary>添加到Cline（VS Code）</summary>

在Cline扩展设置中，添加到MCP服务器：

{
  "mcp-outline": {
    "command": "uvx",
    "args": ["mcp-outline"],
    "env": {
      "OUTLINE_API_KEY": "<YOUR_API_KEY>",
      "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // 可选
    }
  }
}

</details> <details> <summary>使用pip而不是uvx</summary>

如果你更喜欢使用pip：

pip install mcp-outline

然后在你的客户端配置中，将"command": "uvx"替换为"command": "mcp-outline"并移除"args"行：

{
  "mcp-outline": {
    "command": "mcp-outline",
    "env": {
      "OUTLINE_API_KEY": "<YOUR_API_KEY>",
      "OUTLINE_API_URL": "<YOUR_OUTLINE_URL>" // 可选
    }
  }
}

</details> <details> <summary>Docker部署（HTTP）</summary>

对于远程访问或Docker容器，使用HTTP传输。这将在端口3000上运行MCP服务器：

docker run -p 3000:3000 \
  -e OUTLINE_API_KEY=<YOUR_API_KEY> \
  -e MCP_TRANSPORT=streamable-http \
  ghcr.io/vortiago/mcp-outline:latest

然后从客户端连接：

{
  "mcp-outline": {
    "url": "http://localhost:3000/mcp"
  }
}

注意：OUTLINE_API_URL应该指向你的Outline实例所在的位置，而不是localhost:3000。

</details>

工具

注意：工具可用性取决于你的访问控制设置。某些工具在只读模式或删除操作受限时会被禁用。

搜索与发现

search_documents(query, collection_id?, limit?, offset?) - 按关键词搜索文档并分页
list_collections() - 列出所有集合
get_collection_structure(collection_id) - 获取集合内的文档层次结构
get_document_id_from_title(query, collection_id?) - 通过标题搜索找到文档ID

文档阅读

read_document(document_id) - 获取文档内容
export_document(document_id) - 导出文档为markdown

文档管理

create_document(title, collection_id, text?, parent_document_id?, publish?) - 创建新文档
update_document(document_id, title?, text?, append?) - 更新文档（支持追加模式）
move_document(document_id, collection_id?, parent_document_id?) - 将文档移动到不同的集合或父文档

文档生命周期

archive_document(document_id) - 归档文档
unarchive_document(document_id) - 从归档中恢复文档
delete_document(document_id, permanent?) - 删除文档（或移动到回收站）
restore_document(document_id) - 从回收站恢复文档
list_archived_documents() - 列出所有已归档的文档
list_trash() - 列出所有在回收站中的文档

评论与协作

add_comment(document_id, text, parent_comment_id?) - 在文档中添加评论（支持线程回复）
list_document_comments(document_id, include_anchor_text?, limit?, offset?) - 查看文档评论并分页
get_comment(comment_id, include_anchor_text?) - 获取特定评论的详细信息
get_document_backlinks(document_id) - 查找引用该文档的其他文档

集合管理

create_collection(name, description?, color?) - 创建新集合
update_collection(collection_id, name?, description?, color?) - 更新集合属性
delete_collection(collection_id) - 删除集合
export_collection(collection_id, format?) - 导出集合（默认：outline-markdown）
export_all_collections(format?) - 导出所有集合

批量操作

batch_create_documents(documents) - 一次创建多个文档
batch_update_documents(updates) - 一次更新多个文档
batch_move_documents(document_ids, collection_id?, parent_document_id?) - 移动多个文档
batch_archive_documents(document_ids) - 归档多个文档
batch_delete_documents(document_ids, permanent?) - 删除多个文档

AI驱动

ask_ai_about_documents(question, collection_id?, document_id?) - 关于你的文档提出自然语言问题

资源

outline://collection/{id} - 集合元数据（名称、描述、颜色、文档数量）
outline://collection/{id}/tree - 层次化的文档树结构
outline://collection/{id}/documents - 集合内文档的平面列表
outline://document/{id} - 文档全文内容（markdown）
outline://document/{id}/backlinks - 引用该文档的其他文档

开发

快速开始自托管Outline

# 生成配置
cp config/outline.env.example config/outline.env
openssl rand -hex 32 > /tmp/secret_key && openssl rand -hex 32 > /tmp/utils_secret
# 更新config/outline.env以包含生成的秘密

# 启动所有服务
docker compose up -d

# 创建API密钥：http://localhost:3030 → 设置 → API密钥
# 添加到.env：OUTLINE_API_KEY=<token>

设置

git clone https://github.com/Vortiago/mcp-outline.git
cd mcp-outline
uv pip install -e ".[dev]"

测试

# 运行测试
uv run pytest tests/

# 格式化代码
uv run ruff format .

# 类型检查
uv run pyright src/

# 检查代码
uv run ruff check .

本地运行

uv run mcp-outline

使用MCP Inspector进行测试

使用MCP Inspector通过交互式UI视觉测试服务器工具。

对于本地开发（使用stdio）：

npx @modelcontextprotocol/inspector -e OUTLINE_API_KEY=<your-key> -e OUTLINE_API_URL=<your-url> uv run python -m mcp_outline

对于Docker Compose（使用HTTP）：

npx @modelcontextprotocol/inspector http://localhost:3000

MCP Inspector

架构说明

速率限制：通过头部跟踪（RateLimit-Remaining，RateLimit-Reset）自动处理，带有指数退避重试（最多3次尝试）。无需配置。

传输模式：

stdio（默认）：直接进程通信
sse：HTTP服务器发送事件（适用于Web客户端）
streamable-http：可流式传输的HTTP传输

连接池：跨实例共享httpx连接池（可配置：OUTLINE_MAX_CONNECTIONS=100，OUTLINE_MAX_KEEPALIVE=20）

故障排除

服务器无法连接？

检查你的API凭据：

# 测试你的API密钥
curl -H "Authorization: Bearer YOUR_API_KEY" YOUR_OUTLINE_URL/api/auth.info

常见问题：

确认OUTLINE_API_KEY在你的MCP客户端配置中正确设置
检查OUTLINE_API_URL是否指向你的Outline实例（默认：https://app.getoutline.com/api）
对于自托管的Outline，确保URL以/api结尾
确认你的API密钥未过期或被撤销

客户端中工具未出现？

只读模式开启？ 检查是否OUTLINE_READ_ONLY=true禁用了写入工具
删除操作禁用？ 检查是否OUTLINE_DISABLE_DELETE=true隐藏了删除工具
AI工具缺失？ 检查是否OUTLINE_DISABLE_AI_TOOLS=true禁用了AI功能
更改环境变量后重启你的MCP客户端

API速率限制错误？

服务器自动处理速率限制并带有重试逻辑。如果你看到持续的速率限制错误：

减少并发操作
检查是否有多个客户端使用相同的API密钥
如果限制对你的使用场景过于严格，请联系Outline支持

Docker容器问题？

容器无法启动：

确保设置了OUTLINE_API_KEY：docker run -e OUTLINE_API_KEY=your_key ...
检查日志：docker logs <container-id>

客户端无法连接：

使用0.0.0.0作为MCP_HOST：-e MCP_HOST=0.0.0.0
验证端口映射：-p 3000:3000
检查传输模式：-e MCP_TRANSPORT=streamable-http

需要更多帮助？

📖 MCP文档
🐛 报告问题

贡献

欢迎贡献！请提交Pull Request。

许可证

本项目根据MIT许可证发布 - 详情请参阅LICENSE文件。

致谢

使用MCP Python SDK构建
使用Outline API进行文档管理