メインコンテンツへスキップ
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経由で起動するhttps://pdf123.xyz/mcp にあるPDF123のサーバー上
入力ディスク上のファイルパス。サーバーがアップロードし、結果を入力の隣に保存するアップロード用ツールで送るファイル
認証情報匿名利用では不要。PDFX_API_KEY は任意すべてのリクエストに X-API-KEY ヘッダーが必要。ないと401が返る
インストールnpx -y @pdf123/mcp不要。クライアントにURLとヘッダーを追加するだけ
ツール97個すべてのカタログを扱う5つのツール7つのツール: describe、convert、pages、misc、security、upload、download
使う場面エージェントがローカルフォルダーの文書を扱うときエージェントまたはホスト型サービスが、すでにAPI経由でアップロードを処理しているとき

ノートパソコン上のコーディングアシスタントにはローカルサーバーを使います。エージェントがクラウドで動いていて、手元のディスクを読めない場合は、ホスト型エンドポイントを使います。

ローカルMCPサーバーをインストールするには?

MCPクライアントが npx でサーバーを起動するため、インストールは不要です。Claude Codeでは、1つのコマンドで追加できます。

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

Claude Desktopは claude_desktop_config.json を、Cursorは .cursor/mcp.json を読み込みます。ほかのクライアントにも、MCPの設定ページまたはファイルがあります。どれも同じ mcpServers のエントリを受け付けます。

MCPクライアントの設定json
{
  "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 を2回呼び出して、ファイルをPDF123にアップロードし、保存したファイルのパスを答えます。結果は最初の入力の隣に保存され、既存のファイルが置き換えられることはありません。同じ操作は、Webサイトでは結合と圧縮として利用できます。

ローカルサーバーにはどのツールがありますか?

サーバーには5つのツールがあります。merge のようなツールIDは通常の文字列の引数なので、ツールの一覧は小さく保たれます。

ツール機能主な引数
pdf123_list_toolsツールを1行ずつ一覧するgroup、query、format
pdf123_describe_toolツールのフィールド、既定値、許可される値、バッチとして実行されるかどうかを示すtool
pdf123_run_toolローカルファイルに対して1つのツールを実行し、保存したパスまたはJSONレポートを返すtool、files、params、output
pdf123_run_pipeline最大8個のツールを1回のリクエストでつなぐsteps、files、output
pdf123_call任意のツールID、操作ID、/api/... パスに生のリクエストを送るtarget、files、fields

エージェントは通常、pdf123_list_tools でツールを探し、pdf123_describe_tool でそのフィールドを読み、そのあと pdf123_run_tool を呼び出します。IDを打ち間違えると、「もしかして」という候補が返されます。

バッチ、パスワード、パイプラインはどう動作しますか?

  • バッチ。 単一ファイル用のツールに複数のファイルを渡すと、ファイルごとに1件の結果を返すバッチとして実行されます。各ファイルは、終わるたびに保存されます。返答はファイルごとのレポートです。1つでも失敗したファイルがあると、返答はレポート付きのエラーになるため、エージェントは失敗したファイルだけを再試行できます。
  • パスワード。 input_password は、暗号化されたすべての入力を開きます。passwords は、files と同じ順序でファイルごとに1つのパスワードを設定し、ロックされていないファイルには空文字列を指定します。結合のように複数のファイルを受け取るツールでも使えます。
  • パイプライン。 pdf123_run_pipeline は最大8ステップを受け取り、各ステップが次のステップに渡されます。同じパスワードの引数を受け付けます。
  • 生の呼び出し。 pdf123_call を使うと、サーバーより新しい操作にも到達できます。ローカルでの検証は行われません。
  • フィルターツール。 IDが filter- で始まるツールは、条件を満たさないとき {"matched": false} を返します。これはエラーではなく結果です。
  • 再試行。 idempotencyKey は、24時間のあいだ最初の結果を再生します。

エージェントが使えるフォルダーを制限するには?

PDFX_MCP_ROOT にディレクトリを設定します。複数のディレクトリはコロンで区切り、Windowsではセミコロンで区切ります。すると、サーバーはそれらのディレクトリの中でだけ入力を読み、結果を書き込みます。その外側のパス、.. による脱出、外へ通じるシンボリックリンクは、何かをアップロードする前に Code: path_not_allowed で拒否されます。この環境変数がない場合は、サーバーのプロセスが到達できるすべてのパスが許可されます。

ファイルアクセスの制限json
"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 にサーバーを向けられます。詳しくはセルフホストをご覧ください。

結果とエラーはどのような形ですか?

単一の結果は、保存した path、contentType、サイズ bytes を持つ小さなJSONオブジェクトです。バッチの結果は、processed、unmatched、failed、そして files の一覧を持ちます。これらの形は、コマンドラインの pdfx --json と一致します。文書情報のようにレポートを返すツールは、レポートをそのまま返します。

単一の結果json
{
  "path": "/Users/me/Documents/merged.pdf",
  "contentType": "application/pdf",
  "bytes": 1096
}

失敗した呼び出しは、ツールのエラーとして返ります。サーバーが提供していれば、そのテキストの末尾に Reason:、Code:、Hint: の行が付くため、エージェントはコードで分岐できます。

エラーのテキストtext
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を返します。キーは開発者向けページで作成できます。

ホスト型エンドポイントの設定json
{
  "mcpServers": {
    "pdf123": {
      "url": "https://pdf123.xyz/mcp",
      "headers": { "X-API-KEY": "<your-key>" }
    }
  }
}

ホスト型サーバーには7つのツールがあります。pdf_toolbox_describe_operation、pdf_toolbox_convert、pdf_toolbox_pages、pdf_toolbox_misc、pdf_toolbox_security、pdf_toolbox_upload、pdf_toolbox_download です。カテゴリごとの各ツールは、operation 名とそのパラメーターに加えて、ファイルまたはアップロード用ツールが返す fileId を受け取ります。1つの操作のスキーマを取得するには、describeツールを使います。

FAQ

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、または自分のサーバーにアップロードします。ツールの説明には、処理後にそのファイルが削除されると記載されています。結果は自分のマシンに保存されます。詳しくはファイル処理とプライバシーをご覧ください。

エージェントはいくつのツールを使えますか?

ローカルサーバーは、5つのMCPツールを通じて、カタログの97個すべてのツールに到達できます。ホスト型エンドポイントは、操作をカテゴリ(convert、pages、misc、security)ごとにまとめ、7つのMCPツールとして公開しています。