該用哪一個 MCP 伺服器?
兩個伺服器都提供 PDF123 的操作,差別在於執行的位置,以及檔案如何送達。
| 本機:@pdf123/mcp | 託管:/mcp | |
|---|---|---|
| 執行位置 | 在你的電腦上,由 MCP 用戶端透過 stdio 啟動 | 在 PDF123 的伺服器上,位址為 https://pdf123.xyz/mcp |
| 輸入 | 磁碟上的檔案路徑。伺服器負責上傳,並把結果存在輸入檔案旁邊 | 透過上傳工具送出的檔案 |
| 憑證 | 匿名使用不需要。PDFX_API_KEY 為選用 | 每個請求都要帶 X-API-KEY 標頭。沒有就會回應 401 |
| 安裝 | npx -y @pdf123/mcp | 不需要。把網址與標頭加進用戶端即可 |
| 工具 | 以五個工具涵蓋完整的 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_API_BASE 可以讓伺服器改為連到你自己的 pdfx-server;請參閱自架。
結果與錯誤長什麼樣子?
單一結果是一個小型 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 工具。
相關頁面
- 給 Claude Code、Codex 與 Cursor 使用的 Agent Skill,有一個對應整個目錄,另外每個工具各有一個
- /llms.txt,以純文字列出工具、API 與 MCP 端點的索引
- 共用同一份目錄的 pdfx 命令列與 TypeScript SDK
- 開發者總覽、OpenAPI 文件與 Swagger UI
- 工具頁:合併、壓縮、OCR、加入密碼、修復
- PDF123 部落格的文章〈為 AI 代理而生,而不只是為瀏覽器〉與〈同一個操作,四種用戶端〉
常見問題
什麼是 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 工具。