Claude CodeでPDFを扱う：変換、トークン、構造の保持

ClaudeではPDFはどのように処理され、なぜ各ページで1,500～3,000トークンを消費するのか？#

Anthropicの公式ドキュメントでは、この処理をわかりやすく3つの手順で説明しています。

筋は通っていますが、処理コストはページ数に比例して増えます。そして、サブスクリプションの上限がPDFひとつで尽きる理由を示す数字があります。

どれほどの量かを示すため、AnthropicはBedrockで同じ3ページのPDFを2つのモードで測定しました。テキストモード（Converse Document Chat）では約1,000トークンでした。視覚分析（Claude PDF Chat）では約7,000トークンでした。画像を含めると処理コストは7倍になります。

ページのスクリーンショットはさらに多く消費します。1,000×1,000ピクセルのスクリーンショットは約1,300トークンを消費します。

仕組みは単純です。ClaudeはOCRを信用しきれないため、PDFはコストが高くなります。テキストと画像の両方を使って照合するので、2つの層の料金を同時に支払うことになります。大きな文書では、別の方法を使えます。ファイルをプロジェクトフォルダーにMarkdownとして保存し、Claudeに「情報が入った文書を渡すので、内容を整理して広げてください」と伝えます。Claudeは内容を自分のファイルに分散し、一度にすべてを消費する代わりに、整理されたテキストを使って作業を続けます。

一般的なタスクではPDFはどれくらい消費するのか？#

具体的な数字（Sonnet 4.xモデル、入力料金は100万トークンあたり$3）：

これは4回のリクエストを1サイクル行っただけの数字です。その後はプロンプトキャッシュが効き始めます（デフォルトのTTLは5分、拡張ティアでは最大1時間で、その時間内の再呼び出しは最大90%割引）。節約額はさらに増えます。

同じPDFを新しいチャットにアップロードするたびに、Claudeはもう一度読み込みます。チャットをまたいでキャッシュは引き継がれません。

同じ15ページのPDFを一度Markdownへ変換し、4つの新規チャットへ.mdとして読み込むと、この例では15 × 300 × 4 = 18,000入力トークンとなり、135,000ではありません。変換後1ページ300、PDF1ページ2,250はこの計算の仮定で、すべてのPDFの実測定数ではありません。自分の文書の数を測り、変換品質を確認してから節約を見積もってください。

Claude Proサブスクリプションでは、この差がさらに大きくなります。100ページのレポートひとつで5時間の上限を使い切ることがあります。Markdownに変換すれば、同じ予算内でそのような文書を10件以上扱えます。

2026年のAnthropic APIにおけるPDFの制限は？#

Anthropicのドキュメントには、上部に制限が記載されています（2026年5月31日現在）。

Claude.ai（一般向けWebアプリ）の制限は異なります。1ファイルあたり最大500 MBで、1チャットあたり最大20ファイルです。ただし、視覚分析が機能するのは100ページ以下のPDFだけです。それを超えると、Claudeにはテキストだけが見え、グラフや図表は見えません。

API経由でPDFを送る方法は3つあります。

1. URL経由 - "source": {"type": "url", "url": "..."} - 文書がオンラインにある場合に最も簡単です。
2. Base64形式 - "source": {"type": "base64", "media_type": "application/pdf", "data": "..."} - ローカルファイル向けです。
3. Files API経由 - "source": {"type": "file", "file_id": "file_abc123"} - 繰り返しのリクエスト向けです。ベータヘッダーanthropic-beta: files-api-2025-04-14が必要です。

同じPDFを複数のチャットで使うときに節約する主な方法はFiles APIです。一度アップロードしてfile_idを取得すれば、以後のやり取りではそれを使います。cache_control: ephemeralを使うと、再度の呼び出しは通常料金の10%になります。

Anthropicは、使用量を抑えるための公式アドバイスも公開しています。

方法1：5分でMarkItDownをセットアップする方法#

MarkItDownはMicrosoftの公式プロジェクトで、AutoGenチームが保守しています。GitHubでは13万4千スター、9,200フォークを獲得しています（2026年5月末時点）。READMEには目的が直接記されています。

対応形式：

• 文書： PDF、DOCX、PPTX、XLSX
• Web： HTML、JSON、XML、CSV
• メディア： 文字起こし付きの音声、EXIFとOCR対応の画像、YouTube動画（字幕経由）
• アーカイブ： ZIP、EPub
• その他： Outlook MSGファイル内のすべての添付ファイル

インストール

要件：Python 3.10以上（macOSには通常すでにインストールされています。Windowsでは別途インストールが必要です）。

pip install 'markitdown[all]'

すべての形式が必要でない場合は、選択したものだけをインストールできます。

pip install 'markitdown[pdf, docx, pptx]'

単一ファイルの変換

最も簡単な方法：

markitdown document.pdf > document.md

実行後、現在のフォルダーにdocument.mdが作成されます。@document.mdを使ってClaude Codeに読み込ませるか、プロジェクトの隣に置いてください。

Python API

スクリプトに組み込みたい場合：

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("research-paper.pdf")
print(result.text_content)

# You can save it straight away:
with open("research-paper.md", "w") as f:
    f.write(result.text_content)

MarkItDownでできないこと

• スキャンPDFのOCR - 何も返しません。スキャン文書にはPyMuPDF4LLMまたはDoclingが必要です。
• 複雑な複数段組みレイアウト - 読む順序が乱れることがあります。
• PDFに埋め込まれたURL - 保持されません。

レポート、記事、ドキュメントなどの単純なPDFには、MarkItDownが最適です。1分でインストールでき、Pythonの知識も必要ない、汎用性の高いツールです。キリル文字やスキャン文書での性能は、AI向けにPDFをテキストに変換する方法の分析にある測定結果で示しています。

方法2：PyMuPDF4LLMでできることと、優れている場面#

MarkItDownは対応形式の幅を提供し、PyMuPDF4LLMはPDF処理の深さを提供します。

2026年5月31日現在のバージョンは1.27.2.3です（2026年4月24日リリース）。

含まれる機能

• 正しい読み順での複数段組みページ対応
• 表をGitHub Flavored Markdownに変換
• ヘッダーとフッターを自動削除
• 相対リンク付きで画像を抽出し、別フォルダーに保存
• スマートOCR：読み取り不能な領域だけに適用し、処理時間を約50%短縮
• ネイティブのCエンジン、GPU不要

インストール

pip install pymupdf4llm

使い方

import pymupdf4llm

# Basic use - straight to Markdown:
md_text = pymupdf4llm.to_markdown("document.pdf")

# Save it:
with open("document.md", "w") as f:
    f.write(md_text)

約束どおり、1行で実行できます。

python3 -c "import pymupdf4llm; \
  open('document.md','w').write(pymupdf4llm.to_markdown('document.pdf'))"

MarkItDownよりPyMuPDF4LLMを選ぶ場面

• 保持する必要のあるリンクがPDFに多数含まれている場合（MarkItDownでは失われます）。
• 文書がスキャンされており、OCRが必要な場合。
• ローカルで数千ファイルを高速に処理したい場合（ネイティブCエンジンはPythonラッパーより高速です）。
• さらに処理するため、PDF内の画像を別フォルダーに取り出す必要がある場合。

ライセンスの詳細（ビジネス向けの重要事項）

PyMuPDF4LLMはデュアルライセンスです：AGPL v3またはArtifex商用ライセンス。

AGPLの意味：公開SaaSでライブラリを使う場合、サービスのソースコード全体を同じAGPLライセンスで公開する必要があります（自分のノートPCでスクリプトを使うような社内利用には制限がありません）。

コードを公開せずに商用開発を行うには、Artifex（artifex.com）からライセンスを購入してください。価格は公表されていないため、営業に問い合わせてください。

顧客向けの製品を開発する場合は、最初にライセンスを確認してください。MITライセンスのMarkItDownとDoclingのほうが、SaaSでは安全です。

方法3：Claude Code MCP 設定でMarkItDownサーバーを接続する#

CLIモードのMarkItDownは「事前に手動でファイルを変換する」方式です。MCPサーバーは「変換するタイミングをClaude Codeが決める」方式です。

インストール

uvパッケージマネージャーが必要です。サーバーを別途インストールする必要はありません。uvが初回起動時にダウンロードします。

Claude Codeでの設定

バージョンを固定したまま、1つのコマンドですべてのプロジェクトにサーバーを接続できます。

claude mcp add --scope user --env 'ORT_DISABLE_TELEMETRY=1' --env 'UV_PYTHON=3.12' --transport stdio markitdown -- uvx markitdown-mcp@0.0.1a7
claude mcp list

markitdownの項目に「Connected」と表示されるはずです。初回起動時には約70個のパッケージをダウンロードするため、最大1分かかります。その後のサーバー起動は1～2秒です。

このコマンドに2つの変数が必要な理由は次のとおりです。ORT_DISABLE_TELEMETRY=1は、サーバー内のonnxruntimeエンジンがMacとLinuxでデフォルトでMicrosoftに送信する統計情報を無効にします。UV_PYTHON=3.12は、Windows、Linux、Apple Silicon搭載Mac向けのビルド済みパッケージがあるPython 3.12でサーバーを実行します。Intel MacとmacOS 13以前では、Python 3.14でサーバーをインストールできません。Intel環境でPython 3.12を使う場合は注意点があります。2026年6月以降、Intel用のビルド済みパッケージがないため、uvがcryptographyライブラリをソースからビルドします。インストールに時間がかかり、失敗することもあります。Python 3.12がない場合、uvがダウンロードします。

サーバーはコンピューター上で直接実行され、アクセス権のあるすべてのファイルを開けます。Claude Codeを開いていた場合は再起動すると、MCPサーバー一覧にmarkitdownが表示されます。

使い方

Claude Codeで、次のように伝えるだけです。

Convert /Users/your-user/Documents/report.pdf to Markdown and analyze the main points.

Claudeは自分でconvert_to_markdown(uri)を呼び出してMarkdownを受け取り、それを使って作業します。PDFはコンテキストに読み込まれません。

対応URI

• file:// - ローカルファイル
• http://、https:// - オンライン文書
• data: - インラインデータ（Base64）

セキュリティ

公式READMEからの引用：

デフォルトではlocalhostにバインドします。HTTP/SSE（オプション--http --host 127.0.0.1 --port 3001）で実行する場合、認証済みリバースプロキシなしでポートを外部に公開しないでください。

タスクに合う方法は？#

詳しい比較表：

Markerはベンチマークで優れた精度の数値を公表しています。

ただし、Markerで高速に処理するにはGPUが必要で、機械学習モデルも付属します。通常のテキストPDFを扱う大半のタスクには、GPUなしでも数秒で処理できるPyMuPDF4LLMかMarkItDownで十分です。

選び方の簡単な目安

1. PDFが1、2件で、とにかく速く済ませたい - MarkItDown CLI。
2. PDFが数十件あり、自動化したい - MarkItDown MCPサーバー、またはスクリプト内のPyMuPDF4LLM。
3. 構造の保持が重要な、リンクや画像を含むPDF - PyMuPDF4LLM。
4. 表の安定性が重要な、本番環境の業務用RAG - Docling。
5. 数式を含む科学論文 - Marker。
6. 変換について考えず、Claudeに任せたい - MarkItDown MCPサーバー。

文書フォルダーを自動変換するスクリプトをすぐ使える形で書く方法#

実用例を考えてみましょう。証券会社の明細書、契約書、プレゼン資料など、顧客のPDFとPPTXレポートが40件、1つのフォルダーに入っています。フォルダーをそのままClaudeにアップロードしても役に立ちません。最初の応答を得る前に、コンテキストウィンドウが情報で埋まってしまいます。以下のスクリプトでフォルダー全体を一度に処理してから、大きなPDFの代わりに軽量な.mdファイルを使って作業を続けましょう。

このスクリプトをプロジェクトルートのscripts/docs-to-md.shとして保存します。

#!/bin/bash
# docs-to-md.sh - converts all documents in a folder to Markdown using MarkItDown
# Usage: bash docs-to-md.sh ./documents

set -e

INPUT_DIR="${1:-./documents}"
OUTPUT_DIR="${INPUT_DIR}/_md"

mkdir -p "$OUTPUT_DIR"

echo "Scanning $INPUT_DIR..."

for file in "$INPUT_DIR"/*.{pdf,docx,pptx,xlsx}; do
  [ -f "$file" ] || continue

  basename=$(basename "$file")
  name="${basename%.*}"
  output="$OUTPUT_DIR/${name}.md"

  if [ -f "$output" ] && [ "$output" -nt "$file" ]; then
    echo "Skipping $basename (already converted)"
    continue
  fi

  echo "Converting $basename..."
  markitdown "$file" > "$output"
done

echo "Done. Results are in $OUTPUT_DIR"

実行可能にします。

chmod +x scripts/docs-to-md.sh

実行します。

bash scripts/docs-to-md.sh ./reports

実行後、./reports/_md/にすべての文書の.md版が保存されています。@reports/_md/を使ってClaude Codeに読み込ませ、PDFの代わりに圧縮されたテキストを使って作業できます。

スクリプトは、すでに変換したファイル（.mdファイルがソースより新しいもの）を自動的にスキップします。再実行しても低コストで、すべてを変換し直すことはありません。

冪等性と差分変換

同じ名前のまま再保存されたPDFの変更を検出するには、コンテンツハッシュのチェックを追加します。

hash=$(shasum -a 256 "$file" | cut -d' ' -f1)
hash_file="$OUTPUT_DIR/.${name}.sha256"

if [ -f "$hash_file" ] && [ "$(cat "$hash_file")" = "$hash" ]; then
  echo "Skipping $basename (hash matches)"
  continue
fi

markitdown "$file" > "$output"
echo "$hash" > "$hash_file"

この方法では、内容が変わった場合にだけファイルを再変換します。

ClaudeではPDFのほうがMarkdownより適しているのはどんな場合か？#

Markdown変換では不十分な3つのケース：

1. 図やグラフの視覚分析

Claudeにグラフ（価格推移、プロセス図、アーキテクチャ図など）を「読ませる」必要がある場合、その情報はMarkdownにはありません。Markdownで保持されるのは図のキャプションだけで、図そのものは失われます。

解決策：PDFをアップロードし、視覚モードを明示的に有効にします。Claude APIではフラグが自動で機能しますが、AWS Bedrockではcitationsフラグが必要です。

2. 結合セルがある複雑な表

Markdownの表は平坦です。PDFに結合セル、複数段のヘッダー、または入れ子の小さな表があると、変換ツールは表を平坦化するか、関連性を失わせます。

解決策：PDFを直接使うか、Doclingを使う（複雑な表の処理に最適です）か、変換後に手作業で書式を整えます。

3. ページ参照が必要な成果物としての文書

法律文書、契約書、議事録では、「7ページ、3段落目」と引用できることが重要です。Markdownではページ番号が失われます。

解決策：PDF + Files API + プロンプトキャッシュを使います。一度アップロードしてfile_idで参照すれば、Claudeはページ番号を保持した状態で文書を確認し、特定ページを引用できます。

短い文書

PDFが2ページ未満で、1回しか使わないなら、変換する価値はありません。PDFの5,000トークンに対してMarkdownは800トークンですが、MarkItDownをインストールするほどの節約ではありません。

損益分岐点は約5ページ以上、または同じ文書を2回以上使う場合です。それ未満ならPDFを直接アップロードし、それ以上なら変換します。

ClaudeでPDFを扱うときによくある5つの間違い#

1. 同じPDFを新しいチャットに毎回アップロードする

Claude Proには5時間あたりのメッセージ上限があります。50ページのレポートひとつで、2つ目の質問をする前に使い切ることがあります。

そのためのシンプルな原則は、1つのタスクにつき1つのチャットです。AIが異常な量のトークンを使い始めるのは、すべてを1つのチャットに詰め込み、PDFを何度も読み込ませているということです。各ウィンドウでは小さなタスクを1つずつ扱いましょう。文書を一度Markdownに変換し、プロジェクトと一緒に各新規ウィンドウへ.mdファイルを追加します。コンテキストウィンドウの円は黄色になりません。

解決策：一度Markdownに変換するか、file_idとプロンプトキャッシュを使うFiles APIを利用します。

2. テキストの代わりにスクリーンショットを使う

よくある例として、コードや表をClaudeに見せようとして、1920×1080画面全体のスクリーンショットを撮り、5回リクエストしただけで上限に達した理由がわからない、というケースがあります。

1,000×1,000ピクセルのスクリーンショットは約1,300トークンを消費します。同じテキストを手でコピーすれば50～100トークンです。13～26倍の差です。

解決策：スクリーンショットの範囲を重要な部分だけに絞るか、もっとよい方法として、テキストを直接コピーしてください。

3. OCRなしのスキャンPDF

MarkItDownはOCRができません。スキャン文書を変換すると、空の.mdファイル（または意味のない3行）ができます。

解決策：スキャンには、組み込みのスマートOCRがあるPyMuPDF4LLMかDoclingを使います。

4. 100ページの上限を見落とす

Anthropicのドキュメントに記載された上限は1リクエストあたり600ページですが、コンテキストが200Kのモデル（Sonnet 4.x、Opus 4.x）では実際の上限は100ページです。600ページの上限は旧モデルまたは特別なティア向けです。

150ページのレポートをSonnet 4.6にアップロードすると、エラーになるか、さらに悪い場合には、最初の100ページだけを処理したのに文書全体を読んだかのようにClaudeが振る舞います。

解決策：長いPDFはアップロード前に分割します。またはMarkdownに変換します。ページ数の上限はなく、トークン数の上限だけです。

5. 繰り返しのリクエストでプロンプトキャッシュを使わない

同じ文書をAPI経由で扱う場合は、cache_control: ephemeralでラップします。5分以内の再呼び出しは初回料金の10%です。最初のリクエストは高く、残りは90%割引になります。

解決策：複数回アップロードするものには、デフォルトでプロンプトキャッシュを有効にします。

次に読む：コンテキストエンジニアリング#

PDFからMarkdownへの変換は、トークンを節約する方法のひとつです。それだけではClaudeの回答精度は上がりません。精度を高めるのはコンテキストエンジニアリングです。質問する前にモデルのコンテキストへ何を入れるかを決める分野です。

CLAUDE.mdが800行あり、プロジェクトに不要なMCPサーバーが10個あり、さらに100ページのPDFを読み込ませるなら、Markdown変換で防げるのは漏れの1つだけで、残る3つはそのままです。そのため、次のガイドを用意しています。

• Claude Codeでトークンはどこに消えるのか - PDFだけでなく、コンテキストが漏れる9つのパターン。
• 2026年のコンテキストエンジニアリング - コンテキストを体系的に管理する方法。
• Claude CodeのPlan Mode - Claudeがコードを書き始める前に使う計画モード。