Readeck MCP

一个 MCP 服务器，将 Readeck 库变成 AI 代理的读写知识库：代理可以将生成的 HTML 直接推入 Readeck（由 LLM 自动打标签），之后可以检索并读取这些文档。基于 FastMCP 构建 — 同一套代码既可以作为本地 stdio 服务器运行，也可以作为反向代理后面的远程 HTTP 服务器运行。

与现有的 Readeck MCP（只读的阅读助手）不同，这个 摄取代理生成的 HTML，并用 LLM 从固定分类表中自动打标签。

工具

readeck_save 使用 Readeck 的 JSON 创建 API，带有原始 HTML 的 html 字段（base64/data-URI 不起作用）。它会发送浏览器 User-Agent，这样 WAF（例如 Cloudflare 错误 1010）不会阻止它，并短暂轮询以返回新书签的 id、word_count 和 reading_url。

Related MCP server: Doc Monitor MCP

自动打标签

当你调用 readeck_save 而不提供 labels 时，LLM 会对文档进行分类。它在设计上具有抗注入能力：模型只能从固定分类表（LABEL_TAXONOMY）中选择，结果会在服务端与该列表取交集，因此不可能出现词汇表之外的标签。来源标签（ORIGIN_LABEL，默认 propio）总是由代码添加，而不是 LLM。

与提供商无关（兼容 OpenAI 或 Anthropic）。适用于 Groq 等免费层级 — 对于像 gpt-oss 这样的推理模型，设置一个较大的 LLM_MAX_TOKENS，服务器会自动发送 reasoning_effort: low。

护栏

• 默认关闭的 HTTP 认证：在 HTTP 传输下，每次工具调用都需要 Authorization: Bearer $MCP_AUTH_TOKEN（恒定时间比较）。

• 输入验证：HTML 大小上限、拒绝非 HTML、URL 方案白名单、标签清理 + 上限。

• 每个进程的令牌桶速率限制。

• LLM 调用在 429/5xx 时重试并退避，优雅降级（打标签是尽力而为；失败永远不会阻止保存）。

配置（环境）

本地（stdio）

READECK_TOKEN=... uv run --script server.py --selftest   # smoke test

使用 MCP 客户端（mcpServers）注册，例如：

{
  "mcpServers": {
    "readeck": {
      "command": "uv",
      "args": ["run", "--script", "/path/to/readeck-mcp/server.py"],
      "env": { "READECK_URL": "https://readeck.example.com", "READECK_TOKEN": "..." }
    }
  }
}

远程（HTTP / Docker）

以 READECK_MCP_TRANSPORT=http 运行（见 Dockerfile）。将其放在反向代理 / 隧道后面，例如 https://mcp-readeck.example.com。当与 Readeck 同地部署时，设置 READECK_URL=http://readeck:8000 以跳过公网往返。将客户端指向端点：

{
  "mcpServers": {
    "readeck": {
      "type": "http",
      "url": "https://mcp-readeck.example.com/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}

注意： 使用端点路径时不要带尾部斜杠（/mcp，而不是 /mcp/）— 某些代理会将尾部斜杠重定向变成 307，从而破坏流式 HTTP 客户端。

在暴露端点之前，总是设置一个安全的 MCP_AUTH_TOKEN — 该令牌授予对库的写入权限。

许可证

MIT