benspdf

---

AI エージェント向けの Ben の PDF ツールを、Model Context Protocol（MCP）経由で利用できます。

メモ

PDF はお使いのマシン上で読み込まれ、アップロードされることはありません。ホスト型モデルを使う場合、質問はそのモデルに送信されます。ツールをローカルの Ollama モデルと組み合わせれば、マシンの外に何も送信されません。

Claude Desktop、Claude Code、VS Code、Kiro、Cursor、ChatGPT デスクトップアプリ、およびその他の MCP クライアントで動作します。上記のワンクリックボタンを使うには uv が必要です。それ以外のクライアントを使う場合や、手動で設定する場合は、セットアップを参照してください。

ツール

ツール	機能
pdf_page_count	PDF のページ数を数えます
pdf_metadata	タイトル、作成者、日付、作成ソフトなどの文書プロパティを読み取ります
pdf_check_text	PDF が読み取り可能なテキストか、OCR が必要なスキャン画像かを判定します
pdf_extract_text	PDF に含まれるテキストをページごとに読み取ります
pdf_page_layout	ページサイズ、向き、回転、ページボックスを確認します
pdf_check_access	暗号化の状態と、印刷、コピー、編集などファイルで許可されている操作を確認します
pdf_render_pages	ページを画像に変換し、ページを見られるようにします
pdf_ocr	OCR でスキャン画像を読み取り、検索可能なテキストレイヤーを追加することもできます
create_test_pdf_file	動作確認に便利な使い捨て PDF を生成します
export	結果をディスク上の指定場所に保存します
list_artifacts	最近の一時的な結果を一覧表示します
discard	一時的な結果をすぐに削除します

1 つを除き、どのツールもパッケージ以外のものを必要としません。pdf_ocr は Python パッケージではなくシステムプログラムの tesseract を使用します。これは実際に呼び出したときにのみ検索されるため、OCR を使う場合にインストールしてください（brew install tesseract、sudo apt install tesseract-ocr、または winget install UB-Mannheim.TesseractOCR）。それ以外の機能は、インストールの有無にかかわらず動作します。

結果の保存先

ツールが新しい PDF を作成すると、作成されたファイルはユーザー自身のフォルダーではなく一時フォルダーに保存され、art_a1b2c3d4.pdf のような短い ID が返されます。ファイルパスを受け付ける場所ならどこでもこれらの ID を使えるため、複数の手順を連続して実行できます。

結果には ID に加えてアーティファクトの path も含まれるため、エクスポートせずに、レンダリングされたページや中間ファイルをすぐに開けます。

自分のフォルダーに書き込むツールは export だけなので、指示するまで何も表示されません。サーバーを起動するたびに、7 日より古い一時ファイルは削除されます。BENSTOOLS_WORKSPACE を設定すると、一時フォルダーを ~/.benstools/work 以外の場所に指定できます。

セットアップ

uvを一度インストールし、クライアントで uvx benspdf-mcp を指定してください。初回実行時に uv がパッケージと適切な Python を取得します。

# macOS and Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

macOS では、brew install uv でもインストールできます。

以下の設定のいずれかを使ってサーバーをクライアントに追加し、クライアントの UI からサーバーを再起動してください。接続したら、自然な言葉で質問するだけです。

~/Downloads/report.pdf は何ページありますか？

Claude Desktop

claude_desktop_config.json を編集します。このファイルは、macOS では ~/Library/Application Support/Claude/ に、Windows では %APPDATA%\Claude\ にあります。Settings → Developer → Edit Config から開くこともできます。

{
  "mcpServers": {
    "benspdf": {
      "command": "uvx",
      "args": ["benspdf-mcp"]
    }
  }
}

Claude Code

設定ファイルは不要で、コマンド 1 つで追加できます。現在のプロジェクトだけでなく、どこでも使えるようにするには --scope user を追加してください。

claude mcp add benspdf -- uvx benspdf-mcp

claude mcp list で接続を確認してください。

VS Code

ワークスペース内の .vscode/mcp.json、またはユーザープロファイル内の同じファイルを使います。VS Code では mcpServers ではなく servers を使い、type の明示的な指定が必要です。

{
  "servers": {
    "benspdf": {
      "type": "stdio",
      "command": "uvx",
      "args": ["benspdf-mcp"]
    }
  }
}

Kiro

ワークスペース内の .kiro/settings/mcp.json、またはどこでも使えるようにするには ~/.kiro/settings/mcp.json を使います。autoApprove を設定すると、信頼するツールの確認プロンプトを省略できます。

{
  "mcpServers": {
    "benspdf": {
      "command": "uvx",
      "args": ["benspdf-mcp"],
      "autoApprove": ["pdf_page_count"]
    }
  }
}

Cursor

上部のボタンを使えば設定できます。手動で設定する場合、どこでも使えるようにするには ~/.cursor/mcp.json、プロジェクト内だけで使うには .cursor/mcp.json を使います。

{
  "mcpServers": {
    "benspdf": {
      "type": "stdio",
      "command": "uvx",
      "args": ["benspdf-mcp"]
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json を使います。Cascade の Settings → Cascade → Manage MCPs → View raw config から開くこともできます。パスはバージョンによって変更されているため、こちらから開くのがおすすめです。

{
  "mcpServers": {
    "benspdf": {
      "command": "uvx",
      "args": ["benspdf-mcp"]
    }
  }
}

Continue

~/.continue/config.yaml、またはプロジェクト内の .continue/mcpServers/ にある .yaml ファイルを使います。ここで紹介しているクライアントのうち、Continue だけは上記の JSON 形式ではなく、YAML を使います。また、mcpServers は名前をキーとするオブジェクトではなく、リストです。

mcpServers:
  - name: benspdf
    command: uvx
    args:
      - benspdf-mcp

ChatGPT デスクトップアプリ、Codex CLI、Codex IDE 拡張機能

この 3 つはすべて Codex クライアントで、設定ファイル ~/.codex/config.toml を共有しているため、一度サーバーを追加すればすべてで使えます。この設定ファイルは JSON ではなく TOML です。

[mcp_servers.benspdf]
command = "uvx"
args = ["benspdf-mcp"]

その他の MCP クライアント

ほとんどのクライアントでは、上記の Claude Desktop と同じ JSON を使います。つまり、command を uvx に、args を ["benspdf-mcp"] に設定した mcpServers オブジェクトです。"type": "stdio" の明示的な指定を求めるクライアントもあります。必須でない場合でも追加して問題ありません。

実行するコマンドを尋ねられた場合は、次のとおりです。

uvx benspdf-mcp

Ollama を使った完全オフラインでの利用

上記のクライアントでは PDF をローカルに保持できますが、回答にはホスト型モデルが使われます。代わりにローカルモデルとツールを組み合わせれば、データがマシンの外部に送信されることはありません。

モデルを取得済みの Ollama と、次のパッケージが必要です。

pip install benspdf-mcp ollama
ollama pull llama3.1

次に、同梱の CLI を実行します。

benspdf-cli                        # uses the first model you have
benspdf-cli --model llama3.1       # or pick one
BENSPDF_MODEL=llama3.1 benspdf-cli # or set it once

python -m benspdf.cli でも同じ処理を実行できます。ソースコードをチェックアウトしている場合に便利です。

You: how many pages in ~/Downloads/report.pdf?
[Using tool: pdf_page_count]
[Result: 12 pages in report.pdf]
Assistant: The PDF has 12 pages.

リファレンス

各ツールの説明には、その機能と使用するタイミングが記載されているため、通常は何かを調べる必要はありません。ツールが返すすべてのフィールドや、回答に至った理由など、詳しい情報が必要な場合は、ツールリファレンスを参照してください。

コードに取り組む場合は、CONTRIBUTING.mdを参照してください。

ライセンス

Apache 2.0