Paperless-NGX MCP Server

Paperless-NGX MCP 服务

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

快速入门

安装

1. 安装 MCP 服务：

npm install -g paperless-mcp

2. 将其添加到 Claude 的 MCP 配置中：

对于 VSCode 扩展，编辑 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json：

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
    }
  }
}

对于 Claude 桌面应用，编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "paperless": {
      "command": "npx",
      "args": ["paperless-mcp", "http://your-paperless-instance:8000", "your-api-token"]
    }
  }
}

3. 获取 API 令牌：

   1. 登录 Paperless-NGX 实例
   2. 点击右上角的用户名
   3. 选择“My Profile”
   4. 点击圆形箭头按钮生成新令牌

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

   • 将 http://your-paperless-instance:8000 替换为 Paperless-NGX URL
   • 将 your-api-token 替换为刚刚生成的令牌

就这样！现在你可以让 Claude 帮你管理 Paperless-NGX 文档了。

使用示例

你可以让 Claude 执行以下操作：

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

可用工具

文档操作

list_documents

获取所有文档的分页列表。

参数：

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

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

get_document

根据 ID 获取指定文档。

参数：

• id：文档 ID

get_document({
  id: 123
})

search_documents

在文档中进行全文搜索。

参数：

• query：搜索查询字符串

search_documents({
  query: "invoice 2024"
})

download_document

根据 ID 下载文档文件。

参数：

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

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

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 数组
  • permissions：用于 set_permissions 的对象，包含 owner、permissions 和 merge 标志
  • metadata_document_id：用于 merge，指定元数据来源
  • 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]
})

post_document

将新文档上传到 Paperless-NGX。

参数：

• file：经过 Base64 编码的文件内容
• filename：文件名
• 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 数组

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"
})

标签操作

list_tags

获取所有标签。

list_tags()

create_tag

创建新标签。

参数：

• name：标签名称
• color（可选）：十六进制颜色代码（例如 "#ff0000"）
• match（可选）：要匹配的文本模式
• matching_algorithm（可选）：取值为 "any"、"all"、"exact"、"regular expression" 或 "fuzzy" 之一

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

联系人操作

list_correspondents

获取所有联系人。

list_correspondents()

create_correspondent

创建新联系人。

参数：

• name：联系人名称
• match（可选）：要匹配的文本模式
• matching_algorithm（可选）：取值为 "any"、"all"、"exact"、"regular expression" 或 "fuzzy" 之一

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

文档类型操作

list_document_types

获取所有文档类型。

list_document_types()

create_document_type

创建新的文档类型。

参数：

• name：文档类型名称
• match（可选）：要匹配的文本模式
• matching_algorithm（可选）：取值为 "any"、"all"、"exact"、"regular expression" 或 "fuzzy" 之一

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

错误处理

以下情况会显示明确的错误消息：

• Paperless-NGX URL 或 API 令牌不正确
• 无法连接到 Paperless-NGX 服务
• 请求的操作失败
• 提供的参数无效

开发

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

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 通信，适用于命令行和直接集成。

npm run start -- <baseUrl> <token>

2. HTTP（Streamable HTTP Transport）

要将服务作为 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。