Paperless-NGX MCP 服务器

用于与 Paperless-NGX API 服务器交互的 MCP（Model Context Protocol）服务器。该服务器提供用于管理 Paperless-NGX 实例中的文档、标签、通信方和文档类型的工具。

快速开始

安装

将这些内容添加到您的 MCP 配置文件中：

// STDIO 模式（推荐用于本地或 CLI 使用）

"paperless": {
  "command": "npx",
  "args": [
    "-y",
    "@baruchiro/paperless-mcp@latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

// HTTP 模式（推荐用于 Docker 或远程使用）

"paperless": {
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "ghcr.io/baruchiro/paperless-mcp:latest",
  ],
  "env": {
    "PAPERLESS_URL": "http://your-paperless-instance:8000",
    "PAPERLESS_API_KEY": "your-api-token",
    "PAPERLESS_PUBLIC_URL": "https://your-public-domain.com"
  }
}

3. 获取您的 API 令牌：

   1. 登录您的 Paperless-NGX 实例

   2. 点击右上角的用户名

   3. 选择"我的个人资料"

   4. 点击圆形箭头按钮以生成新令牌

4. 替换 MCP 配置中的占位符：

   • 将 http://your-paperless-instance:8000 替换为您的 Paperless-NGX URL

   • 将 your-api-token 替换为您刚刚生成的令牌

   • 将 https://your-public-domain.com 替换为您的公共 Paperless-NGX URL（可选，回退到 PAPERLESS_URL）

环境变量

就是这样！现在您可以请 Claude 帮助您管理 Paperless-NGX 文档。

使用示例

以下是一些您可以请 Claude 做的事情：

• "显示所有标记为'发票'的文档"

• "搜索包含'纳税申报表'的文档"

• "创建一个名为'收据'的新标签，颜色为 #FF0000"

• "下载文档 #123"

• "列出所有通信方"

• "创建一个名为'银行对账单'的新文档类型"

Related MCP server: paperless-mcp

可用工具

文档操作

list_documents

获取带简单筛选器的分页文档列表。用于简单的列表任务。对于全文查询、结构化自定义字段筛选或高级 Paperless 筛选，请使用 query_documents。

参数：

• page（可选）：页码

• page_size（可选）：每页文档数

• search（可选）：简单的 Paperless 搜索词

• correspondent（可选）：通信方 ID

• document_type（可选）：文档类型 ID

• tag（可选）：标签 ID

• storage_path（可选）：存储路径 ID

• created__date__gte（可选）：创建日期晚于或等于 YYYY-MM-DD

• created__date__lte（可选）：创建日期早于或等于 YYYY-MM-DD

• ordering（可选）：Paperless 排序字段

• archive_serial_number（可选）：存档序列号

• archive_serial_number__isnull（可选）：存档序列号是否为空

• custom_field_query（可选）：原始 JSON 编码的 Paperless 自定义字段查询字符串

• custom_fields__icontains（可选）：跨自定义字段值的不区分大小写的子字符串匹配

list_documents({
  page: 1,
  page_size: 25
})

query_documents

规范的文档查询工具。支持全文查询、简单的 Paperless 搜索、自定义字段筛选以及文档化的 /api/documents/ Paperless 查询参数。

参数：

• page（可选）：页码

• page_size（可选）：每页文档数

• ordering（可选）：Paperless 排序字段

• query（可选）：全文查询字符串

• search（可选）：简单的 Paperless 搜索词

• more_like_id（可选）：查找与此文档 ID 相似的文档

• correspondent（可选）：通信方 ID

• document_type（可选）：文档类型 ID

• tag（可选）：标签 ID

• storage_path（可选）：存储路径 ID

• created__date__gte（可选）：创建日期晚于或等于 YYYY-MM-DD

• created__date__lte（可选）：创建日期早于或等于 YYYY-MM-DD

• custom_field_query（可选）：使用 [field_name_or_id, operator, value] 叶子节点或 ["AND" | "OR", [clause1, clause2]] 分组的结构化 Paperless 自定义字段查询

• paperless_filters（可选）：其他文档化的 /api/documents/ Paperless 查询参数，以键/值对形式传递

// Full-text query
query_documents({
  query: "invoice 2024"
})

// Simple search term
query_documents({
  search: "acme"
})

// Custom field exact match
query_documents({
  custom_field_query: ["Invoice Number", "exact", "12345"]
})

// Custom field empty
query_documents({
  custom_field_query: ["OR", [
    ["Invoice Number", "isnull", true],
    ["Invoice Number", "exact", ""]
  ]]
})

// Custom field missing
query_documents({
  custom_field_query: ["Invoice Number", "exists", false]
})

// Combined filters
query_documents({
  query: "invoice",
  tag: 5,
  created__date__gte: "2024-01-01",
  custom_field_query: ["Invoice Number", "exists", true]
})

// One documented Paperless filter that is not a first-class argument
query_documents({
  paperless_filters: {
    id__in: [101, 202, 303]
  }
})

get_document

按 ID 获取特定文档。

参数：

• id：文档 ID

get_document({
  id: 123
})

search_documents

已弃用的全文搜索兼容包装器。新集成请优先使用 query_documents({ query: ... })。

参数：

• query：搜索查询字符串

search_documents({
  query: "invoice 2024"
})

download_document

按 ID 下载文档文件。

参数：

• id：文档 ID

• original（可选）：如果为 true，则下载原始文件而非存档版本

download_document({
  id: 123,
  original: false
})

get_document_thumbnail

按 ID 获取文档缩略图（图像预览）。返回以 base64 编码的 WebP 图像资源形式的缩略图。

参数：

• id：文档 ID

get_document_thumbnail({
  id: 123
})

bulk_edit_documents

对多个文档执行批量操作。

参数：

• documents：文档 ID 数组

• method：以下之一：

  • set_correspondent：为文档设置通信方

  • set_document_type：为文档设置文档类型

  • set_storage_path：为文档设置存储路径

  • add_tag：为文档添加标签

  • remove_tag：从文档移除标签

  • modify_tags：添加和/或移除多个标签

  • delete：删除文档

  • reprocess：重新处理文档

  • set_permissions：设置文档权限

  • merge：合并多个文档

  • split：将一个文档拆分为多个文档

  • rotate：旋转文档页面

  • delete_pages：从文档中删除特定页面

• 基于方法的附加参数：

  • correspondent：用于 set_correspondent 的 ID

  • document_type：用于 set_document_type 的 ID

  • storage_path：用于 set_storage_path 的 ID

  • tag：用于 add_tag/remove_tag 的 ID

  • add_tags：用于 modify_tags 的标签 ID 数组

  • remove_tags：用于 modify_tags 的标签 ID 数组

  • set_permissions：用于 set_permissions 的对象，包含查看/更改用户和组（{"view": {"users": [], "groups": []}, "change": {...}}）。省略的操作/列表将保持不变

  • owner：用于 set_permissions 的用户 ID（或 null 以移除）。除非 merge 为 true，否则省略 owner 会清除当前所有者

  • merge：用于 set_permissions 的布尔值 — true 表示添加到现有权限并保留所有者；false（默认）表示替换列出的用户/组

  • metadata_document_id：用于 merge 的 ID，指定元数据来源

  • delete_originals：用于 merge/split 的布尔值

  • pages：用于 split 的字符串 "[1,2-3,4,5-7]" 或用于 delete_pages 的 "[2,3,4]"

  • degrees：用于 rotate 的数字（90、180 或 270）

示例：

// Add a tag to multiple documents
bulk_edit_documents({
  documents: [1, 2, 3],
  method: "add_tag",
  tag: 5
})

// Set correspondent and document type
bulk_edit_documents({
  documents: [4, 5],
  method: "set_correspondent",
  correspondent: 2
})

// Merge documents
bulk_edit_documents({
  documents: [6, 7, 8],
  method: "merge",
  metadata_document_id: 6,
  delete_originals: true
})

// Split document into parts
bulk_edit_documents({
  documents: [9],
  method: "split",
  pages: "[1-2,3-4,5]"
})

// Modify multiple tags at once
bulk_edit_documents({
  documents: [10, 11],
  method: "modify_tags",
  add_tags: [1, 2],
  remove_tags: [3, 4]
})

// Modify custom fields
bulk_edit_documents({
  documents: [12, 13],
  method: "modify_custom_fields",
  add_custom_fields: [
    { field: 2, value: "year" }
  ],
  remove_custom_fields: []
})

// Set an empty custom field value, e.g. a date field used as a pending marker
bulk_edit_documents({
  documents: [14],
  method: "modify_custom_fields",
  add_custom_fields: [
    { field: 9, value: "" }
  ],
  remove_custom_fields: []
})

post_document

向 Paperless-NGX 上传新文档。

两种上传模式：

1. Base64 模式（传统）：提供 file（base64 编码的内容）+ filename

2. 文件系统模式（高效）：提供 file_path（服务器上的绝对路径）

安全说明： 使用 file_path 时，请设置 PAPERLESS_MCP_UPLOAD_PATHS 环境变量（允许的目录列表，以冒号分隔），以将上传限制在特定位置。如果不设置，服务器文件系统上的任何文件都可能被上传。

参数：

• file（可选）：Base64 编码的文件内容。file 或 file_path 必须提供其一。

• file_path（可选）：服务器文件系统上文件的绝对路径。file 或 file_path 必须提供其一。

• filename（可选）：文件名。与 file 一起使用时为必需，与 file_path 一起使用时为可选（从路径派生）。

• title（可选）：文档的标题

• created（可选）：文档创建时的日期时间（例如 "2024-01-19" 或 "2024-01-19 06:15:00+02:00"）

• correspondent（可选）：通信方 ID

• document_type（可选）：文档类型 ID

• storage_path（可选）：存储路径 ID

• tags（可选）：标签 ID 数组

• archive_serial_number（可选）：存档序列号

• custom_fields（可选）：自定义字段 ID 数组

文件大小限制： 两种模式均为 100MB

// Base64 mode (traditional)
post_document({
  file: "base64_encoded_content",
  filename: "invoice.pdf",
  title: "January Invoice",
  created: "2024-01-19",
  correspondent: 1,
  document_type: 2,
  tags: [1, 3],
  archive_serial_number: "2024-001",
  custom_fields: [1, 2]
})

// Filesystem mode (more efficient for large files)
post_document({
  file_path: "/var/uploads/invoice.pdf",
  title: "January Invoice",
  correspondent: 1,
  document_type: 2,
  tags: [1, 3]
})

文档备注

list_document_notes

列出附加到文档的所有备注。

参数：

• id：文档 ID

list_document_notes({
  id: 123
})

create_document_note

向文档添加备注。返回文档的完整备注列表。

参数：

• id：文档 ID

• note：要添加的备注文本

create_document_note({
  id: 123,
  note: "Invoice paid on 2026-06-30 from Commerzbank account."
})

delete_document_note

⚠️ 按备注 ID 从文档中删除单条备注。此操作不可逆。

参数：

• id：文档 ID

• note_id：要删除的备注的 ID

• confirm：必须为 true 才能确认此破坏性操作

delete_document_note({
  id: 123,
  note_id: 5,
  confirm: true
})

标签操作

list_tags

获取所有标签。

list_tags()

create_tag

创建新标签。

参数：

• name：标签名称

• color（可选）：十六进制颜色代码（例如 "#ff0000"）

• match（可选）：要匹配的文本模式

• matching_algorithm（可选）：0 到 6 之间的数字： 0 - 无 1 - 任意词 2 - 所有词 3 - 精确匹配 4 - 正则表达式 5 - 模糊词 6 - 自动

create_tag({
  name: "Invoice",
  color: "#ff0000",
  match: "invoice",
  matching_algorithm: 5
})

通信方操作

list_correspondents

获取所有通信方。

list_correspondents()

create_correspondent

创建新的通信方。

参数：

• name：通信方名称

• match（可选）：要匹配的文本模式

• matching_algorithm（可选）：0 到 6 之间的数字： 0 - 无 1 - 任意词 2 - 所有词 3 - 精确匹配 4 - 正则表达式 5 - 模糊词 6 - 自动

create_correspondent({
  name: "ACME Corp",
  match: "ACME",
  matching_algorithm: 5
})

文档类型操作

list_document_types

获取所有文档类型。

list_document_types()

create_document_type

创建新的文档类型。

参数：

• name：文档类型名称

• match（可选）：要匹配的文本模式

• matching_algorithm（可选）：0 到 6 之间的数字： 0 - 无 1 - 任意单词 2 - 所有单词 3 - 精确匹配 4 - 正则表达式 5 - 模糊单词 6 - 自动

create_document_type({
  name: "Invoice",
  match: "invoice total amount due",
  matching_algorithm: 1
})

自定义字段操作

list_custom_fields

获取所有自定义字段。

list_custom_fields()

get_custom_field

按 ID 获取特定的自定义字段。

参数：

• id：自定义字段 ID

get_custom_field({
  id: 1
})

create_custom_field

创建新的自定义字段。

参数：

• name：自定义字段名称

• data_type：以下之一："string", "url", "date", "boolean", "integer", "float", "monetary", "documentlink", "select"

• extra_data（可选）：自定义字段的额外数据，例如选择选项

create_custom_field({
  name: "Invoice Number",
  data_type: "string"
})

update_custom_field

更新现有的自定义字段。

参数：

• id：自定义字段 ID

• name（可选）：新的自定义字段名称

• data_type（可选）：新的数据类型

• extra_data（可选）：自定义字段的额外数据

update_custom_field({
  id: 1,
  name: "Updated Invoice Number",
  data_type: "string"
})

delete_custom_field

删除自定义字段。

参数：

• id：自定义字段 ID

delete_custom_field({
  id: 1
})

bulk_edit_custom_fields

对多个自定义字段执行批量操作。

参数：

• custom_fields：自定义字段 ID 数组

• operation：以下之一："delete"

bulk_edit_custom_fields({
  custom_fields: [1, 2, 3],
  operation: "delete"
})

邮件操作

用于管理 Paperless 邮件账户以及驱动自动邮件导入的邮件规则的工具。账户密码/令牌永远不会暴露：它们会从每个工具响应中脱敏。

list_mail_accounts

列出邮件账户，以便你在创建邮件规则时选择所需的账户 ID。密码会被脱敏。

参数：

• page（可选）：页码

• page_size（可选）：每页结果数量

list_mail_accounts()

get_mail_account

按 ID 获取单个邮件账户。密码/令牌字段会被脱敏。

参数：

• id：邮件账户 ID

get_mail_account({
  id: 1
})

process_mail_account

手动触发一个账户的 Paperless 邮件处理。这会根据该账户已启用的邮件规则处理匹配的邮件。

参数：

• id：邮件账户 ID

process_mail_account({
  id: 1
})

list_mail_rules

列出邮件规则，支持可选分页。

参数：

• page（可选）：页码

• page_size（可选）：每页结果数量

list_mail_rules()

get_mail_rule

按 ID 获取单个邮件规则。

参数：

• id：邮件规则 ID

get_mail_rule({
  id: 1
})

create_mail_rule

创建邮件规则。请先使用 list_mail_accounts 选择账户。

必填参数：

• name：规则名称

• account：邮件账户 ID

• folder：要扫描的 IMAP 文件夹（例如 "INBOX"）

常用可选参数：

• enabled（默认 true）：规则是否启用

• filter_from / filter_to / filter_subject / filter_body：匹配收到的邮件

• maximum_age：仅处理此天数以内的邮件

• action：1=删除，2=移动到文件夹，3=标记为已读，4=标记，5=添加标签

• action_parameter：所选操作的目标文件夹/标签

• assign_title_from：1=主题，2=附件文件名，3=不分配

• assign_tags / assign_correspondent / assign_document_type：要应用的元数据

• assign_correspondent_from：1=无，2=邮件地址，3=发件人姓名，4=使用 assign_correspondent

• attachment_type：1=仅附件，2=所有文件（包括内联）

• consumption_scope：1=仅附件，2=完整邮件为 .eml，3=两者

• pdf_layout：0=系统默认，1=文本+HTML，2=HTML+文本，3=仅 HTML，4=仅文本

create_mail_rule({
  name: "Invoices",
  account: 1,
  folder: "INBOX",
  filter_subject: "invoice",
  action: 3,
  attachment_type: 1
})

update_mail_rule

更新现有的邮件规则。只有你提供的字段会被更改。

参数：

• id：邮件规则 ID

• ...create_mail_rule 中任意需要更新的字段

update_mail_rule({
  id: 1,
  enabled: false
})

delete_mail_rule

删除邮件规则。需要显式的确认标志。这会改变未来的邮件导入行为，但不会删除任何现有文档。

参数：

• id：邮件规则 ID

• confirm：必须为 true 才能确认删除

delete_mail_rule({
  id: 1,
  confirm: true
})

错误处理

在以下情况下，服务器会显示清晰的错误消息：

• Paperless-NGX URL 或 API 令牌不正确

• Paperless-NGX 服务器无法访问

• 请求的操作失败

• 提供的参数无效

测试

单元测试

运行单元测试套件（无需外部依赖）：

npm test

E2E 测试

E2E 套件会启动一个空的 Paperless-ngx 实例，运行编译后的 MCP 服务器，并通过 tools/call 请求驱动一个确定性的串行场景——创建标签、通信方和文档类型，上传 PDF，然后对同一文档执行 list / get / search / download / thumbnail / bulk-edit 操作。整个过程不涉及 LLM，也不使用 MCP 之外的 Paperless REST 客户端。

先决条件： Docker、Docker Compose 和 jq。

# 1. Build the MCP server
npm run build

# 2. Start Paperless-ngx
docker compose -f docker-compose.e2e.yml up -d

# 3. Wait for Paperless to be ready, then get a token
TOKEN=$(curl -s -X POST http://localhost:8000/api/token/ \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"admin123"}' | jq -r '.token')

# 4. Start the MCP server
node build/index.js --http --port 3001 \
  --baseUrl http://localhost:8000 --token "$TOKEN" &
MCP_PID=$!

# 5. Run the E2E tests
MCP_URL=http://localhost:3001/mcp \
PAPERLESS_URL=http://localhost:8000 \
PAPERLESS_TOKEN="$TOKEN" \
npm run test:e2e

# 6. Cleanup
kill "$MCP_PID"
docker compose -f docker-compose.e2e.yml down -v

E2E 测试还会在每次拉取请求和推送到 main 时于 CI 中自动运行，覆盖 build/index.js CLI 和已发布的 Docker 镜像。

开发

想要贡献或修改服务器？以下是你需要了解的内容：

1. 克隆仓库

2. 安装依赖：

npm install

3. 对 server.js 进行修改

4. 在本地测试：

node server.js http://localhost:8000 your-test-token

该服务器基于以下工具构建：

• litemcp：用于构建 MCP 服务器的 TypeScript 框架

• zod：TypeScript 优先的 schema 验证

API 文档

此 MCP 服务器实现了 Paperless-NGX REST API 中的端点。有关底层 API 的更多详细信息，请参阅官方文档。

运行 MCP 服务器

MCP 服务器可以通过两种模式运行：

1. stdio（默认）

这是默认模式。服务器通过 stdio 进行通信，适用于 CLI 和直接集成。

npm run start -- <baseUrl> <token>

2. HTTP（可流式 HTTP 传输）

要以 HTTP 服务方式运行服务器，请使用 --http 标志。你也可以使用 --port 指定端口（默认：3000）。此模式需要安装 Express（它已作为依赖包含在内）。

npm run start -- <baseUrl> <token> --http --port 3000

• MCP API 将在指定端口的 POST /mcp 上可用。

• 每个请求都按照 StreamableHTTPServerTransport 模式无状态地处理。

• 对 /mcp 的 GET 和 DELETE 请求将返回 405 Method Not Allowed。

每请求 API 令牌（HTTP/Docker 模式）

在 HTTP 模式下，客户端通过标准的 Authorization 请求头提供 Paperless-NGX API 令牌来进行身份验证：

Authorization: Bearer <paperless-ngx-api-token>

该令牌会直接传递给 Paperless-NGX，因此每个客户端自身的 Paperless 权限会端到端地强制执行。这样，单个服务器实例就可以服务多个用户，每个用户使用自己的令牌。相同的行为也适用于 /mcp 和 /sse 端点。

⚠️ v2.0.0 中的破坏性变更——HTTP 模式现在默认需要身份验证。

以前，没有 Authorization 请求头的请求会静默回退到服务器配置的 PAPERLESS_API_KEY，这导致任何能访问该端口的人都可以使用 HTTP 端点。从 v2.0.0 开始，没有 Bearer 令牌的请求将被拒绝并返回 401 Unauthorized。除非你显式使用 --no-auth 选择启用，否则服务器令牌绝不用于未经身份验证的请求。

从 v1.x 迁移： 如果你依赖旧的回退机制（单个共享的 PAPERLESS_API_KEY，且客户端不发送令牌），你有两个选择：

1. 推荐： 让每个客户端发送 Authorization: Bearer <paperless-token>。

2. 恢复旧行为（仅限受信任/本地网络）：使用 --no-auth 标志启动服务器，例如将其附加到 Docker command/args 或你的 CLI 调用中。这需要配置服务器令牌（PAPERLESS_API_KEY 或 --token）。

MCP 服务器可以使用 Docker 和 Docker Compose 进行部署。Docker 镜像会自动以 HTTP 模式运行，并在 3000 端口上支持 SSE（Server-Sent Events，服务器发送事件）。

Docker Compose 配置

创建 docker-compose.yml 文件：

services:
  paperless-mcp:
    container_name: paperless-mcp
    image: ghcr.io/baruchiro/paperless-mcp:latest
    environment:
      - PAPERLESS_URL=http://your-paperless-ngx-server:8000
      - PAPERLESS_API_KEY=your-paperless-api-key
      - PAPERLESS_PUBLIC_URL=https://paperless-ngx.yourpublicurl.com
    ports:
      - "3000:3000"
    restart: unless-stopped

然后运行：

docker-compose up -d

与 Continue VS Code 扩展一起使用

如果你正在使用 Continue VS Code 扩展，你可以通过 SSE 将其配置为使用 Docker 化的 MCP 服务器。

在工作区根目录创建或编辑 .continue/mcpServers/paperless-mcp.yaml：

name: Paperless
version: 0.0.1
schema: v1
mcpServers:
  - name: Paperless
    type: sse
    url: http://localhost:3000/sse

注意：

• 如果在远程服务器上运行，请将 localhost 替换为你的 Docker 主机的 IP 地址或主机名

• Docker 容器通过环境变量处理身份验证，因此 Continue 配置中无需提供凭据

• SSE 端点在配置的端口（默认：3000）上的 /sse 路径可用

致谢

本项目是 nloui/paperless-mcp 的一个分支。非常感谢原作者的辛勤工作。贡献和改进可能会回馈到上游。

调试

要在 VS Code 中调试 MCP 服务器，请使用以下启动配置：

{
    "type": "node",
    "request": "launch",
    "name": "Debug Paperless MCP (HTTP, ts-node ESM)",
    "program": "${workspaceFolder}/node_modules/ts-node/dist/bin.js",
    "args": [
        "--esm",
        "src/index.ts",
        "--http",
        "--baseUrl",
        "http://your-paperless-instance:8000",
        "--token",
        "your-api-token",
        "--port",
        "3002"
    ],
    "env": {
        "NODE_OPTIONS": "--loader ts-node/esm",
    },
    "console": "integratedTerminal",
    "skipFiles": [
        "<node_internals>/**"
    ]
}

重要： 在调试之前，请取消注释 src/index.ts 中的以下行（大约在第 175 行）：

// await new Promise((resolve) => setTimeout(resolve, 1000000));

这可以防止服务器立即退出，并允许你设置断点和调试代码。