Paperless-ngx

mcp-paperless-ngx

面向 Paperless-ngx 3.x 的 Model Context Protocol 服务
全面覆盖 REST API、感知架构、节省令牌。

---

基于 REST API version 10 构建，并在以下三方面另辟蹊径：

• 覆盖情况清晰。 92 个已记录的端点均已作为工具提供，或在 src/tools/coverage.ts 中列出，并说明未纳入的原因。测试会强制执行这一点，因此 Paperless 新版本新增端点时，会导致 CI 失败，而不会悄然变成不受支持的功能。
• 严控令牌用量。 Paperless 文档包含完整的 OCR 文本。简单封装器默认会返回这些文本，一次搜索就可能耗尽模型的上下文。此处，列表结果会在服务端通过 ?fields= 裁剪，文本由单独的分页工具提供，而且任何列表端点都不会直接传递原始 API 响应——这一点由测试强制保证。参见上下文开销。
• 按需启用功能。 99 个工具会淹没模型的工具列表。工具集让你只公开特定客户端所需的功能，而 --read-only 则会彻底移除所有写入路径。

不支持 Paperless-ngx 2.x：API version 10 引入了此服务假定存在的端点（嵌套标签、文档版本、share_link_bundles、拆分后的 PDF 操作）。

快速开始

npx -y mcp-paperless-ngx --check   # verify connectivity, then exit

Claude Code

claude mcp add paperless --scope user \
  --env PAPERLESS_URL=https://paperless.example.com \
  --env PAPERLESS_TOKEN=your-api-token \
  -- npx -y mcp-paperless-ngx

Claude Desktop、Cursor、Cline 和其他 MCP 客户端

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["-y", "mcp-paperless-ngx"],
      "env": {
        "PAPERLESS_URL": "https://paperless.example.com",
        "PAPERLESS_TOKEN": "your-api-token"
      }
    }
  }
}

获取 API 令牌

Paperless 网页界面 → 你的用户名（右上角）→ 我的个人资料 → API 令牌字段旁边的圆形箭头按钮。

配置

变量	必需	默认值	用途
PAPERLESS_URL	是	—	服务连接到的基础 URL。
PAPERLESS_TOKEN	是	—	API 令牌。也可使用 PAPERLESS_API_KEY。
PAPERLESS_PUBLIC_URL	否	PAPERLESS_URL	为用户构建链接时使用的 URL；如果从外部访问实例时使用了不同名称，则需设置此项。
PAPERLESS_TOOLSETS	否	见下文	以逗号分隔的工具集，或 all。
PAPERLESS_READ_ONLY	否	false	仅公开不会更改任何内容的工具。
PAPERLESS_HEADERS	否	—	额外请求标头，格式为 JSON（{"X-Auth":"…"}）或 Name: value, Name: value。在 Authentik 或 Authelia 等前置身份验证代理后使用时需要设置。
PAPERLESS_DOWNLOAD_DIR	否	系统临时目录	下载文件的写入位置。
PAPERLESS_MAX_PAGE_SIZE	否	100	列表分页大小的上限，无论模型请求的大小是多少。
PAPERLESS_TIMEOUT_MS	否	60000	请求超时时间。
PAPERLESS_API_VERSION	否	10	在 Accept 标头中发送的 REST API 版本。

CLI 标志 --url、--token、--public-url、--toolsets 和 --read-only 会覆盖环境变量。--check 用于验证连接，--list-tools 用于打印已启用的工具。

工具集

工具集	默认状态	内容
documents	开启	搜索、读取、更新、删除、上传、下载、笔记、批量操作和 PDF 操作
metadata	开启	标签、往来对象、文档类型、存储路径
customfields	开启	自定义字段定义
views	开启	已保存的视图
sharing	开启	共享链接和共享链接集合
workflows	开启	自动化规则、触发器、操作
system	开启	全局搜索、统计信息、状态、任务、回收站
mail	关闭	IMAP 账户、邮件规则、已处理邮件
admin	关闭	用户、群组、个人资料、配置、日志（只读）

mail 和 admin 默认关闭，因为大多数会话都用不上它们，而且每增加一个工具，每次请求都会消耗额外上下文。请显式启用它们：

PAPERLESS_TOOLSETS=documents,metadata,system,mail
PAPERLESS_TOOLSETS=all

上下文成本

将 API 封装为供大模型使用的接口，会产生 API 本身没有的成本：模型看到的所有内容都会在每次请求中计费。以下两方面会带来影响，以及此服务如何应对。

响应。 在 Paperless 中，有三种响应形式成本很高，也很容易意外返回：

来源	问题	处理方式
文档列表	每份文档的 content 都包含完整 OCR 文本	使用 ?fields= 在服务端限制响应字段；get_document_content 会单独分页返回文本
/api/search/	会返回所有对象类型中经过完整填充的 Document 对象，其中包含 OCR 文本	对文档进行摘要，其他类型则简化为 id + name
工作流、邮件规则、群组、任务	每个对象有 27–34 个字段，触发器／操作定义以内嵌形式呈现	仅摘要标识字段；嵌套列表折叠为计数。full: true 会返回全部内容

工具定义。 这项成本更高，也更不易察觉：名称、描述和 JSON 架构会随每一次请求发送，无论是否调用任何工具。

工具集	工具数量	每次请求的大致成本
all	99	~20,500 tokens
默认	85	~18,500 tokens
documents,metadata	49	~12,900 tokens

无法让这项成本归零——这是模型可以使用工具而不必猜测所付出的代价。但有意识地控制工具集很有意义：如果你的会话只会搜索和归档文档，设置 PAPERLESS_TOOLSETS=documents,metadata 节省的上下文比任何响应精简方式都多。

安全

此服务提供破坏性操作，因为不能执行这些操作的文档管理器就称不上真正的管理器。它不会试图猜测这些操作何时适用——这项判断应由客户端和用户作出。它会采取以下措施：

• 破坏性工具标注了 destructiveHint: true，以便 MCP 客户端要求用户确认。
• 工具描述会明确说明哪些操作无法撤销（empty_trash、delete_custom_field、delete_originals），并要求在调用前确认。
• --read-only 会从工具列表中移除所有写入工具，而不是等到调用时才拒绝执行。
• 批量端点支持“对所有符合此筛选条件的项目执行操作”模式。此服务不会开放这种模式：批量工具需要明确的 ID 列表，因此错误的筛选条件不会悄无声息地影响整个档案。
• create_share_link 会生成可公开访问的 URL。其描述会明确说明这一点，而且还提供了 audit_sharing 提示词，用于检查已经公开的内容。

与凭据相关的端点（生成令牌、注册 TOTP、禁用他人的第二因素）特意不予开放。完整列表及原因请参见 EXCLUDED_ENDPOINTS。

提示词

在支持 MCP 提示词的客户端中注册为斜杠命令：

提示词	功能
triage_inbox	浏览尚未分类的文档，优先使用现有条目提出元数据建议，并在用户批准前不应用任何更改。
find_document	根据模糊描述查找文档，先以较低成本搜索，再扩大搜索范围。
audit_sharing	检查所有公开共享链接，并标记永不过期的链接。

测试

分为三个层次，因为它们能发现不同的问题：

npm test                                        # logic — no network
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/smoke-test.mjs                   # all 55 read-only tools, live
PAPERLESS_URL=… PAPERLESS_TOKEN=… \
  node scripts/write-test.mjs                   # writes, live — see the warning

npm test 检查此服务自身的逻辑：端点覆盖情况、枚举值是否符合架构、列表工具是否会泄露原始 API 对象，以及只读模式是否确实移除了写入操作。

smoke-test.mjs 检查它对 Paperless 的假设。它会针对真实实例调用每个只读工具，通过列表调用解析 ID，而非将 ID 写死，并打印响应大小，以便留意开销较大的工具。它不会写入任何内容。

write-test.mjs 覆盖其余功能：上传和消费、更新每种字段类型、备注、批量编辑标签、分享链接、旋转，以及一次移入回收站再还原的往返操作。

它只会操作自己创建的对象。 所有创建的对象名称都带有 zz-mcp-test 前缀，并会在最后删除；它绝不会修改自己未上传的文档。如果运行过程中断，带有该前缀的遗留对象可以安全删除。如果有测试实例，建议优先使用。

跟进 Paperless 的变化

PAPERLESS_URL=… PAPERLESS_TOKEN=… node scripts/sync-schema.mjs
npm test

sync-schema.mjs 会根据你自己的实例的 OpenAPI 文档重新生成 schema/endpoints.json。 随后，测试套件会报告所有既未开放、也未明确排除的端点。维护流程就是这样：将其指向较新版本的 Paperless，测试就会告诉你有哪些变化。

开发

npm install
npm start          # run from source
npm run build      # compile to build/
npm test           # unit tests + coverage checks
npm run inspect    # build, then open the MCP inspector

相关项目

已有多个适用于 Paperless-ngx 的 MCP 服务，其中最活跃的两个都支持 3.x： cubinet-code/paperless-ngx-mcp 会在 2.x 和 3.x 之间自动适配；baruchiro/paperless-mcp 则允许你选择 API 版本（PAPERLESS_API_VERSION，默认值为 9）。如果你需要在同一次安装中同时支持两个主版本，可以使用其中之一。

本服务选择了相反的取舍：它假定使用 API 版本 10，不支持更早版本。这样才能调用 3.x 新增的端点——嵌套标签、文档版本、share_link_bundles、独立的 PDF 操作——并通过测试断言已涵盖所有 92 个有文档说明的端点。此外，它还会在服务端通过 ?fields= 精简列表响应，因此默认不会附带 OCR 文本。

许可证

MIT。请参阅 LICENSE。

---

_{由 eichner.cloud 构建 — 可自托管，并且对它相当钟爱。}