Paperless-NGX MCP 服务器

一个用于与 Paperless-NGX API 服务器交互的 MCP (模型上下文协议) 服务器。此服务器提供用于管理 Paperless-NGX 实例中的文档、标签、往来方和文档类型的工具。

快速开始

通过 Smithery 安装

要通过 Smithery 为 Claude Desktop 自动安装 Paperless NGX MCP 服务器，请执行以下操作：

npx -y @smithery/cli install @nloui/paperless-mcp --client claude

手动安装

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. 选择“我的个人资料”
   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: 从文档中删除特定页面
• 基于方法的其他参数：
  • 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 的对象，包含所有者、权限、合并标志
  • metadata_document_id: 用于合并以指定元数据源的 ID
  • delete_originals: merge/split 的布尔值
  • pages: split "[1,2-3,4,5-7]" 或 delete_pages "[2,3,4]" 的字符串
  • degrees: rotate 的数字 (90, 180 或 270)

示例：

// 向多个文档添加标签
bulk_edit_documents({
  documents: [1, 2, 3],
  method: "add_tag",
  tag: 5
})

// 设置往来方和文档类型
bulk_edit_documents({
  documents: [4, 5],
  method: "set_correspondent",
  correspondent: 2
})

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

// 将文档拆分为多个部分
bulk_edit_documents({
  documents: [9],
  method: "split",
  pages: "[1-2,3-4,5]"
})

// 一次修改多个标签
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 的更多详细信息，请参阅官方文档。