DeepSeek-OCR Agent for Claude Code

Claude Code向けのDeepSeek-OCR統合実装。Modal Labs経由でGPU上でDeepSeek-OCRを実行し、高精度なOCR処理を提供します。

特徴

• 高精度OCR: DeepSeek-OCRによる97-98%の精度
• 多言語対応: 日本語、英語、中国語など100以上の言語
• コスト最適化: Modal Labsの無料枠（月$30）で個人利用をカバー
• Claude Code統合: MCPサーバー経由でシームレスに利用可能
• Sub-Agent対応: ocr-specialist エージェントで専門的なOCR処理

アーキテクチャ

Claude Code (Mac)
  └─ MCP Server (Node.js/TypeScript)
      └─ Modal Labs API
          └─ Modal Functions (Python)
              └─ DeepSeek-OCR (GPU: T4, 8GB VRAM)

必要要件

ソフトウェア

• Python 3.12+: Modal CLI実行用
• Node.js 18+: MCPサーバー実行用
• Modal Labs アカウント: modal.comで無料登録

システム要件

• macOS（Apple Silicon / Intel対応）
• インターネット接続（Modal Labs API利用）

セットアップ

1. クイックスタート

# セットアップスクリプトを実行
./scripts/setup.sh

このスクリプトが以下を自動実行します:

• Python/Node.js環境の確認
• Modal CLIのインストール
• Modal認証
• Modal appのデプロイ
• MCPサーバーのビルド
• Claude Desktop設定のガイド

2. 手動セットアップ

Step 1: Modal CLIインストール

pip3 install modal

Step 2: Modal認証

modal token new

ブラウザが開くので、Modal Labsにサインイン/サインアップしてトークンを生成します。

Step 3: Modal Appデプロイ

cd modal_app
modal deploy main.py

Step 4: MCPサーバービルド

cd mcp-server
npm install
npm run build

Step 5: Claude Desktop設定

~/Library/Application Support/Claude/claude_desktop_config.json に以下を追加:

{
  "mcpServers": {
    "deepseek-ocr": {
      "command": "node",
      "args": [
        "/Users/username/deepseek-ocr-agent/mcp-server/dist/index.js"
      ]
    }
  }
}

重要: パスを実際のプロジェクトパスに置き換えてください。

Step 6: Claude Desktopを再起動

設定を反映させるためClaude Desktopを再起動します。

使用方法

Claude Codeでの基本的な使い方

1. 画像をMarkdownに変換

   この画像をMarkdownに変換して: /path/to/document.png
   

2. プレーンテキスト抽出

   この領収書からテキストを抽出: receipt.jpg
   

3. カスタムプロンプト

   この画像から表データだけを抽出してCSV形式で: table.png
   

Sub-Agentの使用

OCR専門タスクには ocr-specialist sub-agentを使用できます:

@ocr-specialist この文書をデジタル化して

詳細な使用方法は USAGE.md を参照してください。

コスト

Modal Labs料金

• 無料枠: 月$30のクレジット
• GPU (T4): $0.000164/秒

月間コスト試算

個人利用（1日100枚、月3,000枚）の場合:

処理時間: 3,000枚 × 3秒 = 9,000秒
コスト: $0.000164 × 9,000 = $1.48/月
無料枠: $30/月

→ 実質$0（無料枠内）

月10,000枚まで無料枠で処理可能です。

トラブルシューティング

Modal認証エラー

modal token new

トークンを再生成してください。

MCPサーバーが認識されない

1. Claude Desktopを再起動
2. 設定ファイルのパスを確認
3. MCPサーバーがビルドされているか確認: ls mcp-server/dist/index.js

OCR処理が失敗する

• 画像ファイルが存在するか確認
• 画像形式がサポートされているか確認（PNG, JPG, JPEG推奨）
• Modal appがデプロイされているか確認: modal app list

処理が遅い

• 初回実行時はコールドスタート（5-10秒）が発生します
• 2回目以降は2-3秒程度に短縮されます

テスト

動作テスト

# テスト用画像を用意
./scripts/test-ocr.sh /path/to/test/image.png

MCPサーバーテスト

cd mcp-server
npm run dev

プロジェクト構造

deepseek-ocr-agent/
├── modal_app/              # Modal Functions（Python）
│   ├── main.py             # DeepSeek-OCR処理のメイン実装
│   └── requirements.txt    # Python依存関係
│
├── mcp-server/             # MCPサーバー（TypeScript）
│   ├── src/
│   │   ├── index.ts        # MCPサーバー本体
│   │   └── tools/
│   │       └── modal-ocr.ts # Modal API統合
│   ├── package.json
│   └── tsconfig.json
│
├── .claude/
│   └── agents/
│       └── ocr-specialist.md # OCR専門sub-agent
│
├── scripts/
│   ├── setup.sh            # セットアップスクリプト
│   └── test-ocr.sh         # テストスクリプト
│
├── config/
│   ├── claude_desktop_config.json  # Claude Desktop設定例
│   └── .env.example        # 環境変数サンプル
│
├── docs/                   # ドキュメント
│   ├── USAGE.md            # 使用方法ガイド
│   ├── DEPLOYMENT.md       # デプロイメントガイド
│   └── SUMMARY.md          # 実装サマリー
│
└── README.md

技術スタック

バックエンド（Modal Functions）

• Python 3.12
• PyTorch 2.6.0
• Transformers 4.46.3
• DeepSeek-OCR（deepseek-ai/DeepSeek-OCR）
• Flash Attention 2.7.3

MCPサーバー

• Node.js 18+
• TypeScript 5.7
• @modelcontextprotocol/sdk
• Axios

インフラ

• Modal Labs（Serverless GPU）
• NVIDIA T4 GPU（8GB VRAM）

ドキュメント

詳細なドキュメントは docs/ ディレクトリにあります:

• USAGE.md: 使用方法と実用例
• DEPLOYMENT.md: デプロイメントとモニタリング
• SUMMARY.md: 実装サマリー

よくある質問

Apple Silicon Macで動作しますか？

はい。ローカルではGPUを使用せず、Modal Labs経由でクラウドGPU（NVIDIA T4）を利用するため、Apple Silicon / Intelどちらでも動作します。

オフラインで使用できますか？

いいえ。Modal Labs APIを使用するためインターネット接続が必要です。

商用利用は可能ですか？

DeepSeek-OCRはMITライセンスです。Modal Labsの利用規約も確認してください。

その他の質問は USAGE.md のFAQセクションを参照してください。

ライセンス

MIT License

参考リンク

• DeepSeek-OCR GitHub
• Modal Labs
• Claude Code Documentation
• Model Context Protocol

貢献

Issue、Pull Requestを歓迎します。

サポート

問題が発生した場合:

1. このREADMEのトラブルシューティングセクションを確認
2. GitHubでIssueを作成
3. Modal Labs ドキュメントを参照