应该使用哪个 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 mcp add pdf123 -- npx -y @pdf123/mcpClaude Desktop 读取 claude_desktop_config.json,Cursor 读取 .cursor/mcp.json。其他客户端有 MCP 设置页面或设置文件。它们都接受同样的 mcpServers 条目。
{
"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。没有设置这个变量时,服务器进程能访问的任何路径都被允许。
"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 一致。返回报告的工具,例如文档信息,会直接在回复中返回报告。
{
"path": "/Users/me/Documents/merged.pdf",
"contentType": "application/pdf",
"bytes": 1096
}失败的调用会作为工具错误返回。如果服务器提供了相应信息,错误文本末尾会有 Reason:、Code: 和 Hint: 行,智能体可以据此按错误码分支处理。
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。可以在开发者页面创建密钥。
{
"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。
相关页面
- 面向 Claude Code、Codex 和 Cursor 的智能体技能,其中一个对应整个目录,另外每个工具各有一个
- /llms.txt,工具、API 和 MCP 端点的纯文本索引
- 共用同一份目录的 pdfx 命令行和 TypeScript SDK
- 开发者概览、OpenAPI 文档和 Swagger UI
- 工具页面:合并、压缩、OCR、加密保护、修复
- PDF123 博客上的文章《为 AI Agent 而建,不只为浏览器:API 怎么用》和《同一操作,四种客户端:浏览器、curl、MCP、pdfx》
常见问题
什么是 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 工具提供。