Smart Excel Reader MCP

Smart Excel Reader MCP Server

Excel設計書を画像として読み取るMCPサーバーです。セル単位の読み取りではなく、シート全体を画像化することでトークン消費を抑え、図形や枠線などの視覚的要素も正確に取得できます。

特徴

• 📊 Excel全体を画像化: セル単位ではなくシート全体を画像として取得
• 🎨 視覚要素の完全再現: 図形、枠線、条件付き書式、グラフなどを正確に表示
• ✂️ 自動トリミング: 余白部分を自動的にカットしてトークン消費を最小化
• 💾 トークン効率: 大量のセルデータを送信する代わりに画像1枚で表現
• 🔍 範囲指定対応: 必要な部分だけを抽出可能
• ⚡ 高精度: Microsoft Excel本体を使用するため100%正確なレンダリング

必要要件

• OS: Windows
• 必須ソフトウェア: Microsoft Excel (インストール済みであること)
• Python: 3.10以上

インストール

1. リポジトリのクローン

git clone 
cd smart-excel-reader-mcp

2. 依存関係のインストール

pip install -e .

または

pip install -r requirements.txt

3. Claude Desktop設定

Claude Desktopの設定ファイル (claude_desktop_config.json) に以下を追加:

uvを使用する場合:

{
  "mcpServers": {
    "smart-excel-reader": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/path/to/smart-excel-reader-mcp",
        "run",
        "smart-excel-reader-mcp"
      ]
    }
  }
}

Pythonを直接使用する場合:

{
  "mcpServers": {
    "smart-excel-reader": {
      "command": "python",
      "args": [
        "-m",
        "smart_excel_reader.server"
      ],
      "env": {
        "PYTHONPATH": "C:/path/to/smart-excel-reader-mcp/src"
      }
    }
  }
}

使用可能なツール

1. excel_to_image

Excelシート全体を画像に変換します。

パラメータ:

• file_path (必須): Excelファイルのパス
• sheet_name (オプション): シート名（指定しない場合はアクティブシート）
• zoom_level (オプション): ズームレベル（デフォルト: 100、範囲: 10-400）
• trim_whitespace (オプション): 余白を自動トリミング（デフォルト: true）

使用例:

"C:\Documents\設計書.xlsx"の"画面設計"シートを画像化してください

トリミング機能について: デフォルトで有効になっており、Excelシートの空白部分を自動的にカットします。これにより画像サイズが大幅に削減され、トークン消費を抑えられます。

2. excel_range_to_image

Excelシートの特定範囲を画像に変換します。

パラメータ:

• file_path (必須): Excelファイルのパス
• range_address (必須): 範囲のアドレス（例: "A1:D10"）
• sheet_name (オプション): シート名
• zoom_level (オプション): ズームレベル
• trim_whitespace (オプション): 余白を自動トリミング（デフォルト: true）

使用例:

"設計書.xlsx"の"詳細設計"シートのA1からF20までを画像化してください

3. list_excel_sheets

Excelファイル内の全シート名を一覧表示します。

パラメータ:

• file_path (必須): Excelファイルのパス

使用例:

"C:\Documents\設計書.xlsx"にはどんなシートがありますか？

使用例

シート全体を画像化

ユーザー: C:\Projects\design.xlsxの"画面一覧"シートを見せてください

Claude: [excel_to_imageツールを使用]
→ 画面一覧シート全体の画像が表示される

特定範囲を画像化

ユーザー: 設計書.xlsxの"DB設計"シートのA1からH30を見たいです

Claude: [excel_range_to_imageツールを使用]
→ 指定範囲の画像が表示される

シート一覧を確認

ユーザー: この設計書にはどんなシートがありますか？

Claude: [list_excel_sheetsツールを使用]
→ シート名のリストが表示される

トラブルシューティング

Excelが起動しない

• Microsoft Excelがインストールされているか確認
• Excelのライセンスが有効か確認
• 管理者権限で実行してみる

pywin32のインポートエラー

pip install --upgrade pywin32
python Scripts/pywin32_postinstall.py -install

画像が真っ白になる

• Excelファイルが破損していないか確認
• 別のシートで試してみる
• zoom_levelを調整してみる（50や150など）

技術詳細

アーキテクチャ

smart-excel-reader-mcp/
├── src/smart_excel_reader/
│   ├── server.py          # MCPサーバー本体
│   ├── excel_converter.py # Excel→画像変換ロジック
│   └── utils.py           # ユーティリティ関数

処理フロー

1. MCPサーバーがツール呼び出しを受信
2. ExcelConverterがwin32comを通じてExcelを起動
3. 指定されたシート/範囲を選択
4. CopyPictureでクリップボードに画像をコピー
5. ImageGrabでクリップボードから画像を取得
6. PNG形式で一時ファイルに保存
7. Base64エンコードしてClaudeに返却
8. 一時ファイルをクリーンアップ

ライセンス

MIT License

貢献

Issue、Pull Requestを歓迎します！

更新履歴

v0.1.0 (2025-01-XX)

• 初回リリース
• 基本的な画像変換機能を実装
• 3つのツール（excel_to_image, excel_range_to_image, list_excel_sheets）を提供