跳到主要内容
PPDF123

面向 AI 智能体的 PDF123 MCP 服务器

MCP(Model Context Protocol,模型上下文协议)是一项开放标准,让 Claude Code、Claude Desktop、Cursor 等 AI 客户端可以调用外部工具。PDF123 提供处理本机文件的本地 MCP 服务器 @pdf123/mcp,以及使用 API 密钥的托管端点。

@pdf123/mcpNode 20.3 或更高版本

安装

npx -y @pdf123/mcp
本页内容

应该使用哪个 MCP 服务器?

两个服务器都提供 PDF123 的操作,区别在于运行位置,以及文件如何到达服务器。

本地:@pdf123/mcp托管:/mcp
运行位置在你的机器上,由 MCP 客户端通过 stdio 启动在 PDF123 服务器上,地址为 https://pdf123.xyz/mcp
输入磁盘上的文件路径。服务器负责上传,并把结果保存在输入文件旁边通过上传工具发送的文件
凭据匿名使用不需要。PDFX_API_KEY 为可选每个请求都带 X-API-KEY 请求头。没有则返回 401
安装npx -y @pdf123/mcp无需安装。把 URL 和请求头添加到客户端即可
工具五个工具即可覆盖完整的 97 个工具目录七个工具:describe、convert、pages、misc、security、upload 和 download
适用场景智能体处理本地文件夹中的文档智能体或托管服务已经通过 API 处理上传

笔记本电脑上的编程助手适合使用本地服务器。智能体在云端运行、无法读取你的磁盘时,请使用托管端点。

如何安装本地 MCP 服务器?

不需要安装任何东西,因为 MCP 客户端会用 npx 启动服务器。在 Claude Code 中,一条命令即可添加。

Claude Codebash
claude mcp add pdf123 -- npx -y @pdf123/mcp

Claude Desktop 读取 claude_desktop_config.json,Cursor 读取 .cursor/mcp.json。其他客户端有 MCP 设置页面或设置文件。它们都接受同样的 mcpServers 条目。

MCP client configurationjson
{
  "mcpServers": {
    "pdf123": {
      "command": "npx",
      "args": ["-y", "@pdf123/mcp"]
    }
  }
}

修改客户端配置后请重启客户端。如果想在路径中保留一份副本,请运行 npm install -g @pdf123/mcp,它会提供 pdf123-mcp 命令。服务器需要 Node 20.3 或更高版本,并且需要能访问 API 基础地址。没有离线模式。

第一次该对智能体说什么?

用日常语言提问,并写明文件。例如:

合并 ~/Documents/a.pdf 和 ~/Documents/b.pdf,然后压缩合并后的结果。

智能体会调用 pdf123_run_pipeline,或调用两次 pdf123_run_tool,把文件上传到 PDF123,并回复已保存文件的路径。结果保存在第一个输入文件旁边,且不会替换已有文件。网站上有同样的操作:合并和压缩。

本地服务器提供哪些工具?

服务器有五个工具。merge 这样的工具 id 只是普通的字符串参数,因此工具列表保持精简。

工具功能主要参数
pdf123_list_tools列出工具,每个一行group、query、format
pdf123_describe_tool显示工具的字段、默认值、允许的取值,以及是否以批量方式运行tool
pdf123_run_tool对本地文件运行一个工具,返回保存路径或 JSON 报告tool、files、params、output
pdf123_run_pipeline在一次请求中串联最多 8 个工具steps、files、output
pdf123_call向任意工具 id、操作 id 或 /api/... 路径发送原始请求target、files、fields

智能体通常先调用 pdf123_list_tools 找到工具,再调用 pdf123_describe_tool 读取其字段,最后调用 pdf123_run_tool。如果 id 拼写错误,会返回“你是不是想用”的建议。

批量处理、密码和流水线如何工作?

  • 批量处理。 给单文件工具传入多个文件时,会以批量方式运行,每个文件对应一条结果。每个文件处理完就会保存。回复是逐文件的报告。如果任何文件失败,回复是附带报告的错误,这样智能体可以只重试失败的文件。
  • 密码。 input_password 打开所有加密的输入。passwords 为每个文件设置一个密码,顺序与 files 相同,未加密的文件用空字符串。这也适用于合并等多文件工具。
  • 流水线。 pdf123_run_pipeline 最多接受 8 个步骤,每一步的输出作为下一步的输入。它接受相同的密码参数。
  • 原始调用。 pdf123_call 可以访问比服务器更新的操作。本地不做任何校验。
  • 过滤类工具。 id 以 filter- 开头的工具在条件不成立时返回 {"matched": false}。这是一个结果,而不是错误。
  • 重试。 idempotencyKey 会在 24 小时内重放第一次的结果。

如何限制智能体可以使用的文件夹?

把 PDFX_MCP_ROOT 设置为一个目录。多个目录之间用冒号分隔,Windows 上用分号。设置后,服务器只会在这些目录内读取输入和写入结果。这些目录之外的路径、.. 越界以及指向目录之外的符号链接,都会在上传任何内容之前被拒绝,并返回 Code: path_not_allowed。没有设置这个变量时,服务器进程能访问的任何路径都被允许。

Restrict file accessjson
"env": { "PDFX_API_BASE": "https://pdf123.xyz", "PDFX_MCP_ROOT": "/Users/me/Documents/pdfs" }

请在客户端的 env 块中设置环境变量,或使用 claude mcp add -e NAME=value。如果想让服务器改用你自己的 pdfx-server,请设置 PDFX_API_BASE;参见自托管。

结果和错误是什么样子的?

单个结果是一个小的 JSON 对象,包含保存的 path、contentType 和以 bytes 表示的大小。批量结果包含 processed、unmatched、failed 和 files 列表。这些结构与命令行中的 pdfx --json 一致。返回报告的工具,例如文档信息,会直接在回复中返回报告。

Single resultjson
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

失败的调用会作为工具错误返回。如果服务器提供了相应信息,错误文本末尾会有 Reason:、Code: 和 Hint: 行,智能体可以据此按错误码分支处理。

Error texttext
HTTP 400: This PDF is password-protected. Enter its password.
Reason: password_required
Code: bad_request
Hint: Provide the document password, or unlock the PDF first.

如果工具 id 有拼写错误,错误信息会列出相近的 id,并以 Code: unknown_tool 结尾。如果工具没有可返回的内容,例如对没有表格的 PDF 运行 pdf-to-csv,会返回 Code: no_content,而不是空文件。参见错误码。

如何使用托管 MCP 端点?

API 在 POST https://pdf123.xyz/mcp 内嵌了一个 MCP 服务器。身份验证使用与 REST API 相同的 X-API-KEY 请求头。没有密钥时端点返回 401。可以在开发者页面创建密钥。

Hosted endpoint configurationjson
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

托管服务器列出七个工具:pdf_toolbox_describe_operation、pdf_toolbox_convert、pdf_toolbox_pages、pdf_toolbox_misc、pdf_toolbox_security、pdf_toolbox_upload 和 pdf_toolbox_download。每个类别工具接收一个 operation 名称及其参数,以及一个文件或由上传工具返回的 fileId。用 describe 工具可以获取某个操作的 schema。

常见问题

什么是 MCP?

MCP(Model Context Protocol,模型上下文协议)是一项把 AI 客户端连接到外部工具的开放标准。Claude Code 等客户端会启动或连接 MCP 服务器,列出它的工具,并代表用户调用这些工具。

本地 MCP 服务器可以离线使用吗?

不可以。它会把文件上传到 PDF123 API,或 PDFX_API_BASE 指定的服务器,再把结果保存到本地。API 基础地址必须可以访问。

需要 API 密钥吗?

本地服务器匿名使用时不需要密钥。如果你的服务器要求密钥,请设置 PDFX_API_KEY。位于 /mcp 的托管端点始终需要 X-API-KEY 请求头。

智能体可以读取我电脑上的任何文件吗?

默认情况下,它可以读取服务器进程能访问的任何路径。把 PDFX_MCP_ROOT 设置为你选定的目录,即可将读取和写入限制在这些目录内。

我的文件会怎样处理?

本地服务器会把每个输入上传到 PDF123 API 或你自己的服务器进行处理。工具说明中写明,文件在处理完成后会在那里被删除。结果保存在你的机器上。详情请阅读文件隐私页面。

智能体可以使用多少个工具?

本地服务器通过五个 MCP 工具可访问目录中的全部 97 个工具。托管端点按类别(convert、pages、misc 和 security)分组其操作,并通过七个 MCP 工具提供。