Pdf MCP

🚀 pdf-mcp

Model Context Protocol (MCP) サーバーで、AIエージェントがPDFファイルから内容を読み取り、検索し、抽出できるようにします。PythonとPyMuPDFを使用して構築され、SQLiteベースのキャッシュを備えており、サーバーを再起動してもデータを保持できます。

mcp-name: io.github.jztan/pdf-mcp

✨ 主な機能

• さまざまなPDF操作に対応した8つの専用ツール
• SQLiteキャッシュ — サーバーの再起動後もキャッシュが保持されます（STDIOトランスポートに必須）
• ページ単位の読み取り — 大きなPDFを管理しやすいチャンクで読み取ることができます
• 全文検索 — ドキュメント全体を読み込まずに内容を検索できます
• 画像抽出 — 画像をbase64 PNG形式で抽出できます
• URLサポート — HTTP/HTTPS URLからPDFを読み取ることができます

📦 インストール

pip install pdf-mcp

🚀 クイックスタート

claude mcp add pdf-mcp -- pdf-mcp

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

code --add-mcp '{"name":"pdf-mcp","command":"pdf-mcp"}'

{
  "servers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

codex mcp add pdf-mcp -- pdf-mcp

[mcp_servers.pdf-mcp]
command = "pdf-mcp"

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp",
      "args": [],
      "disabled": false
    }
  }
}

{
  "mcpServers": {
    "pdf-mcp": {
      "command": "pdf-mcp"
    }
  }
}

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

インストールの確認

pdf-mcp --help

💻 使用例

基本的な使用法

pdf_info — ドキュメント情報の取得

ページ数、メタデータ、目次、ファイルサイズ、および推定トークン数を返します。ドキュメントを読み取る前に、まずこれを呼び出してドキュメントを理解してください。

"Read the PDF at /path/to/document.pdf"

pdf_read_pages — 特定のページの読み取り

コンテキストサイズを管理するために、選択したページを読み取ります。

"Read pages 1-10 of the PDF"
"Read pages 15, 20, and 25-30"

pdf_read_all — ドキュメント全体の読み取り

一度に完全なドキュメントを読み取ります。ページ数には安全制限があります。

"Read the entire PDF (it's only 10 pages)"

pdf_search — PDF内の検索

内容を読み込む前に関連するページを見つけます。

"Search for 'quarterly revenue' in the PDF"

pdf_get_toc — 目次の取得

"Show me the table of contents"

pdf_extract_images — 画像の抽出

"Extract images from pages 1-5"

pdf_cache_stats — キャッシュ統計情報の表示

"Show PDF cache statistics"

pdf_cache_clear — キャッシュのクリア

"Clear expired PDF cache entries"

高度な使用法

大きなドキュメントの例 (例: 200ページの年次報告書)

ユーザー: "Summarize the risk factors in this annual report"

エージェントのワークフロー:
1. pdf_info("report.pdf")
   → 200ページ、目次によると「Risk Factors」は89ページ

2. pdf_search("report.pdf", "risk factors")
   → 関連するページ: 89-110

3. pdf_read_pages("report.pdf", "89-100")
   → 最初のバッチ

4. pdf_read_pages("report.pdf", "101-110")
   → 2番目のバッチ

5. チャンクから回答を合成する

🔧 技術詳細

キャッシュ

サーバーは永続的なキャッシュにSQLiteを使用しています。これは、STDIOトランスポートを使用するMCPサーバーが各会話ごとに新しいプロセスとして起動されるために必要です。

キャッシュの場所: ~/.cache/pdf-mcp/cache.db

キャッシュされるデータ:

キャッシュの無効化:

• ファイルの更新時間が変更されたときに自動的に行われます
• pdf_cache_clear ツールを使用して手動で行うことができます
• TTL: 24時間 (設定可能)

設定

環境変数:

# キャッシュディレクトリ (デフォルト: ~/.cache/pdf-mcp)
PDF_MCP_CACHE_DIR=/path/to/cache

# キャッシュのTTL (時間単位、デフォルト: 24)
PDF_MCP_CACHE_TTL=48

開発

git clone https://github.com/jztan/pdf-mcp.git
cd pdf-mcp

# 開発用依存関係を含めてインストール
pip install -e ".[dev]"

# テストの実行
pytest tests/ -v

# 型チェック
mypy src/

# リンティング
flake8 src/

# フォーマット
black src/

pdf-mcpの利点

🤝 コントリビューション

コントリビューションは大歓迎です。プルリクエストを送信してください。

📄 ライセンス

MIT — LICENSE を参照してください。

🔗 リンク

• PyPI
• GitHub
• MCP Documentation
• How I Built pdf-mcp — このプロジェクトの背景にある物語
• MCP Server Security: 8 Vulnerabilities — MCPサーバーを構築する際のセキュリティの教訓