Paperless-NGX MCP Server

Paperless-NGX MCP 服务

用于与 Paperless-NGX API 服务交互的 MCP（Model Context Protocol）服务。此服务提供用于管理 Paperless-NGX 实例中的文档、标签、往来联系人和文档类型的工具。

快速开始

安装

将以下内容添加到 MCP 配置文件中：

// STDIO 模式（推荐用于本地或命令行使用）

"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. 选择“My Profile”
   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 执行的一些操作：

• “显示所有标记为‘Invoice’的文档”
• “搜索包含‘tax return’的文档”
• “创建一个名为‘Receipts’、颜色为 #FF0000 的新标签”
• “下载文档 #123”
• “列出所有往来联系人”
• “创建一个名为‘Bank Statement’的新文档类型”

可用工具

文档操作

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（可选）：结构化的 Paperless 自定义字段查询，使用 [field_name_or_id, operator, value] 叶节点或 ["AND" | "OR", [clause1, clause2]] 分组
• 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：删除文档中的指定页面
• 根据 method 而定的其他参数：
  • 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

端到端测试

端到端测试套件会启动一个空的 Paperless-ngx 实例，运行编译后的 MCP 服务，并通过 tools/call 请求执行确定性的串行场景：创建标签、联系人和文档类型，上传 PDF，然后针对同一文档依次测试列表／获取／搜索／下载／缩略图／批量编辑。无需大模型，也无需在 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

端到端测试也会在每个拉取请求以及每次推送到 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 为先的架构验证工具

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）。

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 扩展，可以将其配置为通过 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 端点位于已配置端口上的 /sse（默认值：3000）

致谢

此项目是 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));

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