跳至主要內容
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不需要。把網址與標頭加進用戶端即可
工具以五個工具涵蓋完整的 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_API_BASE 可以讓伺服器改為連到你自己的 pdfx-server;請參閱自架。

結果與錯誤長什麼樣子?

單一結果是一個小型 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 工具。

常見問題

什麼是 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 工具。