无纸化-mcp

Name: 无纸化-mcp
Author: nloui

作者：nloui102 星标更新：2025-11-11

安装使用来源：spider==github.com

项目介绍

Paperless-NGX MCP 服务器

这是一个用于与 Paperless-NGX API 服务器交互的 MCP（模型上下文协议）服务器。该服务器提供了管理 Paperless-NGX 实例中的文档、标签、联系人和文档类型的工具。

快速开始

安装

安装 MCP 服务器：

npm install -g paperless-mcp

将其添加到您的 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"]
    }
  }
}

获取您的 API 令牌：
1. 登录到您的 Paperless-NGX 实例
2. 点击右上角的用户名
3. 选择“我的资料”
4. 点击圆形箭头按钮生成新的令牌
替换 MCP 配置中的占位符：
- 将 http://your-paperless-instance:8000 替换为您自己的 Paperless-NGX URL
- 将 your-api-token 替换为您刚刚生成的令牌

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

示例用法

这里有一些您可以请求 Claude 做的事情：

"显示所有标记为 '发票' 的文档"
"搜索包含 '税务申报' 的文档"
"创建一个名为 '收据' 的标签，颜色为 #FF0000"
"下载文档 #123"
"列出所有联系人"
"创建一个名为 '银行对账单' 的文档类型"

可用工具

文档操作

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: "发票 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：merge 的元数据来源 ID
- delete_originals：merge/split 的布尔值
- pages：split/delete_pages 的字符串 "[1,2-3,4,5-7]" 或 "[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: "一月发票",
  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: "发票",
  color: "#ff0000",
  match: "发票",
  matching_algorithm: "fuzzy"
})

联系人操作

list_correspondents

获取所有联系人。

list_correspondents()

create_correspondent

创建一个新的联系人。

参数：

name：联系人名称
match（可选）：匹配的文本模式
matching_algorithm（可选）：以下之一 "any", "all", "exact", "regular expression", "fuzzy"

create_correspondent({
  name: "ACME 公司",
  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: "发票",
  match: "发票总金额应付款",
  matching_algorithm: "any"
})

错误处理

如果出现以下情况，服务器会显示清晰的错误消息：

Paperless-NGX URL 或 API 令牌不正确
无法访问 Paperless-NGX 服务器
请求的操作失败
提供的参数无效

开发

想要贡献或修改服务器？这里是你需要知道的内容：

克隆仓库
安装依赖项：

npm install

修改 server.js 文件
本地测试：

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 方法不允许。