excel-vision-mcp

Name: excel-vision-mcp
Author: VOYAGER-Inc

ローカル

github.com/VOYAGER-Inc生産性2013 週間前に更新

リポジトリ

excel-vision-mcp について

Excel Vision MCP は、xlsx ファイルの読み書きを行う MCP サーバーです。セル内の埋め込み画像を ImageContent として取り出し、テキスト、書式マーカー、数式とあわせて返します。図や注釈を含む表の分析に向いており、ファイルはローカルで処理されます。

主な機能

01セル位置に対応付けた埋め込み画像の抽出
02テキスト、書式マーカー、画像をまとめて取得
03参照されない限り非表示の行と列をスキップ
04ワークブックの作成とセル・数式の書き込み
05原子的な保存による元ファイルの保護

活用シーン

01フローチャートを含む要件定義書をアシスタントにレビューさせる
02セルの色や取り消し線で示された状態を読み取る
03MCP クライアントから表の一括書き込みや書式設定を行う

MCP 対応

このプロジェクトは、シートの一覧取得、内容の読み取り、画像の抽出、検索、Excel ファイルへの書き込みのツールを MCP クライアントに提供する MCP サーバーです。

設定

ローカルサーバーの設定はどのクライアントでも共通です。コピーしてクライアントの MCP 設定ファイルに貼り付けてください。

mcp.json · 共通設定

{
  "mcpServers": {
    "voyager-inc-excel-vision": {
      "command": "uvx",
      "args": [
        "excel-vision-mcp"
      ]
    }
  }
}

起動コマンドuvx excel-vision-mcp

ローカルサーバーにはマシン上の実行環境（Node.js 18 以上など）が必要です。設定ファイルの場所はクライアントごとに異なります。

パッケージ

pypiexcel-vision-mcp1.2.1stdio

ツール

掲載時のツール一覧 · 2 週間前に更新

パラメーター	型	必須	説明
file_path	string	はい

詳細

📊 Excel Vision MCP

AI はスプレッドシートを読み取れます。しかし、セル B12 の図は見えません。

これで解決します。 他の Excel MCP サーバーはセルの値を返すだけで、埋め込まれた画像をすべて黙って除外するため、仕様書で必要なフローチャートがモデルに届きません。Excel Vision MCP は、テキスト、書式、数式とともに、AI が実際に確認できるネイティブの ImageContent として画像を返します。

インストール · ツール · 設定 · 仕組み · FAQ

🤔 問題点

アシスタントに要件仕様書のレビューを依頼してみてください。意味の半分は、セルに貼り付けられたスクリーンショット、フローチャート、注釈付きの図に込められています。しかし、すべての Excel MCP サーバーがモデルに渡すのはテキストだけです。モデルは画像の存在を知らないため、自信ありげでも不完全な回答が返ってきます。

同じ見落としは、作成者が残すほかの手がかりにも当てはまります。

作成者の操作	他の MCP サーバーが報告する内容	Excel Vision MCP が報告する内容
`B12` にフローチャートを貼り付けた	何もなし	画像そのものと、`B12` への位置情報
キャンセルした行に取り消し線を引いた	`Legacy export`	`Legacy export [S]` — 取り消し線
レビュー対象の行を強調表示した	`Pending`	`Pending [HL:yellow]`
内部コストの列を非表示にした	非表示の値も通常どおり表示	数式で必要な場合を除き、スキップ

同じファイルでも、あるエージェントに見えるのは文字列の表だけで、もう一方には作成者が実際に伝えようとした内容が見えます。

✨ 主な機能

機能	説明
🖼️ 画像の抽出	埋め込まれたすべての画像を、セル位置と対応付けて抽出します
📄 コンテンツの一括読み取り	テキストと画像を一度の呼び出しで取得し、見落としを防ぎます
🏷️ 書式を考慮した読み取り	太字、取り消し線、ハイライト、フォントの色を報告し、エージェントがテキストだけでなく意図も読み取れるようにします
🙈 非表示コンテンツへの対応	数式で必要なものは保持しつつ、既定では非表示の行や列をスキップします
✍️ 書き込み対応	ブックの作成、セルの更新、数式の書き込み、画像の挿入ができます
🎨 書式設定	色、フォント、罫線、配置、表示形式、自動列幅調整に対応します
🛡️ アトミック保存	書き込みに失敗しても、元のファイルが破損することはありません
📊 スマートページネーション	コンテキストを圧迫せずに、大規模なスプレッドシートを処理します
🔍 テキスト検索	すべてのシートからコンテンツをすばやく検索できます
🔒 完全ローカル処理	ファイルがマシンの外部に送信されることはありません
⚡ 高速	16MB のファイルと 40 枚の画像を約 4 秒で処理します
🖥️ クロスプラットフォーム	macOS、Linux、Windows に対応します

画像抽出 — ここが違います

ほとんどの Excel MCP サーバーはセルの値しか読み取りません。このサーバーは二重抽出方式を採用しています。

セル位置との対応付け（主方式） — openpyxl-image-loader を使用して、各画像を正確なセル位置に対応付けます
アーカイブのスキャン（フォールバック） — xlsx の ZIP アーカイブ内にある xl/media/ ディレクトリをスキャンし、方式 1 で見つからなかった画像を検出します

その結果、画像を一枚も取りこぼさず、取得可能な場合は位置のメタデータも付与されます。

👀 実際の動作を見る

ワークフローは貼り付けられた図に、ステータスはセルの色に示されている要件仕様書です。

あなた： この仕様書を確認して、対象範囲に残っている機能と、ディスパッチのフローを教えてください。

read_full_content は書式マーカー付きのシートをテキストとして返し、その後に埋め込み図を画像として返します。

Row 1: A1: Feature [B] [HL:blue] | B1: Status [B] [HL:blue]
Row 2: A2: Vehicle dispatch  | B2: Approved [HL:green]
Row 3: A3: Legacy CSV export [S] | B3: Cancelled [S]
Row 4: A4: Driver roll call  | B4: Needs review [HL:yellow]

ℹ️ Skipped 3 hidden row(s) with content. Pass include_hidden=true to read them.

**[Image 1]** Sheet: `Spec` | Cell: `B12` | Original: 1180×840px
[the actual flowchart, as ImageContent]

モデルはこれで、質問の両方に回答できます。「従来の CSV エクスポートは取り消し線が引かれ、キャンセル済みと表示されているため、対象範囲に残っている機能は 3 つです。また、B12 のフローチャートには、割り当ての前に点呼による確認が必要と示されています。」

画像に対応していなければ、質問の後半には答えられません。書式に対応していなければ、キャンセル済みの行が有効な行と同じに見えてしまいます。

🚀 クイックスタート

`uvx` でインストール（推奨）

インストールは不要です。直接実行できます。

uvx excel-vision-mcp

`pip` でインストール

pip install excel-vision-mcp

続けて実行します。

excel-vision-mcp

ソースからインストール

git clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git
cd excel-vision-mcp
uv sync
uv run excel-vision-mcp

Docker で実行

docker build -t excel-vision-mcp .
docker run --rm -i -v /path/to/spreadsheets:/data excel-vision-mcp

このサーバーは標準入力／標準出力経由で JSON-RPC を使用するため、アタッチして実行する必要があります（-i）。ファイルが格納されているディレクトリをマウントし、コンテナ内のパス（/data/report.xlsx）を指定してください。イメージでは EXCEL_VISION_MCP_ALLOWED_DIRS=/data が設定されているため、読み取りと書き込みはマウントしたディレクトリ内に限定されます。

MCP クライアントの設定例：

{
  "mcpServers": {
    "excel-reader": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/spreadsheets:/data", "excel-vision-mcp"]
    }
  }
}

🔧 設定

MCP クライアントの設定ファイルにサーバーを追加します。

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json（macOS）または %APPDATA%\Claude\claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Cursor

プロジェクトのルートにある .cursor/mcp.json を編集します。

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Windsurf / VS Code (Copilot)

MCP 設定ファイルを編集します。

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

Antigravity IDE

~/.gemini/config/mcp_config.json を編集します。

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"]
    }
  }
}

注：設定を編集した後、新しいサーバーを読み込むために IDE／クライアントを再起動してください。

ファイルアクセスの制限（任意）

デフォルトでは、サーバーはユーザーアカウントがアクセスできるすべての Excel ファイルを読み書きできます。特定のディレクトリ内に制限するには、EXCEL_VISION_MCP_ALLOWED_DIRS を設定します（複数のパスは macOS／Linux では :、Windows では ; で区切ります）。

{
  "mcpServers": {
    "excel-reader": {
      "command": "uvx",
      "args": ["excel-vision-mcp"],
      "env": {
        "EXCEL_VISION_MCP_ALLOWED_DIRS": "/Users/me/Documents/spreadsheets:/Users/me/Projects/data"
      }
    }
  }
}

🛠️ 利用可能なツール

`list_sheets`

すべてのシートについて、サイズ、結合セルの数、画像の合計数を一覧表示します。まずこのツールを使って、ワークブックの構造を把握してください。

list_sheets(file_path="/path/to/file.xlsx")

戻り値： シート名、行×列のサイズ、データ範囲、結合セルの数、画像の合計数。

`read_excel_data`

ページネーションに対応しており、指定したシートからセルのデータを読み取ります。

read_excel_data(
    file_path="/path/to/file.xlsx",
    sheet_name="Sheet1",      # optional, defaults to first sheet
    start_row=1,              # optional, 1-indexed
    max_rows=200,             # optional, default 200
    include_hidden=False      # optional, read hidden rows/columns too
)

戻り値： 行ごとに整理されたセルの値と、座標ラベル、結合セルおよび書式を示すマーカー。

Row 1: A1: Feature [B] [HL:blue] | B1: Status [B] [HL:blue]
Row 3: A3: Legacy export [S] | B3: Cancelled [S]
Row 4: A4: Report | B4: Needs review [HL:yellow] | C4: Urgent [B] [C:red]

マーカー	意味
`[M]`	結合セル
`[B]` `[I]` `[S]`	太字・斜体・取り消し線
`[HL:color]`	背景のハイライト（色名。例：`yellow`、`red`）
`[C:color]`	フォントの色
`[HIDDEN-REF]`	表示されている数式が参照しているため保持された非表示セル

マーカーと簡単な凡例は、書式が実際に使われているシートにのみ表示されるため、書式のないシートでは余分なコンテキストを消費しません。

`extract_images`

ワークブックに埋め込まれたすべての画像を、base64 の ImageContent として抽出します。

extract_images(
    file_path="/path/to/file.xlsx",
    sheet_name="Overview",    # optional, None = all sheets
    max_width=1024,           # optional, resize limit
    max_height=1024           # optional, resize limit
)

戻り値： メタデータ（セル位置、シート名、元のサイズ）付きの ImageContent（base64）の一覧。

`read_full_content` ⭐

目玉のツールです。 すべてのテキストデータと埋め込み画像を、1 回の呼び出しで読み取ります。文書の包括的な分析に最適です。

read_full_content(
    file_path="/path/to/file.xlsx",
    max_rows_per_sheet=500,   # optional
    max_image_width=1024,     # optional
    max_image_height=1024     # optional
)

戻り値： ワークブックの全内容。すべてのシートのデータが書式マーカー付きの構造化テキストとして含まれ、その後にセル位置との対応情報付きで埋め込み画像がすべて続きます。

使用例： 「この要件文書を分析し、ワークフロー図も含めてすべてのユースケースを要約してください。」

非表示の行と列

すべての読み取りツールは、デフォルトで非表示の行と列をスキップします。非表示にした作成者が、レビュー対象のコンテンツではないことを示しているためです。

例外が 1 つあります。 表示されている数式が参照する非表示のセルは、値が表示されている結果に影響するため、[HIDDEN-REF] のマークを付けて返されます。スキップされたコンテンツは常に報告されるため、何も通知なく消えることはありません。

ℹ️ Skipped 2 hidden row(s) with content. 1 hidden cell(s) are shown anyway
   because visible formulas reference them. Pass include_hidden=true to read them.

すべてのデータを読み取るには、read_excel_data、read_full_content、または search_excel に include_hidden=true を渡してください。

`get_workbook_overview`

ワークブックの構造をすばやく要約します。ファイルサイズ、シート一覧、サイズ、画像数を確認できます。

get_workbook_overview(file_path="/path/to/file.xlsx")

`search_excel`

ワークブック内のすべてのセルを対象に、大文字と小文字を区別せずにテキストを検索します。

search_excel(
    file_path="/path/to/file.xlsx",
    query="revenue",
    sheet_name="Q4 Report"    # optional, None = all sheets
)

返される内容： 一致したセルのシート名、座標、値です。結果は最大 100 件です。

`create_excel_file`

指定したシートを含む、新しい空のワークブックを作成します。

create_excel_file(
    file_path="/path/to/new.xlsx",
    sheet_names=["Summary", "Detail"],  # optional, default ["Sheet1"]
    overwrite=False                     # optional, refuses to replace by default
)

`add_excel_sheet`

既存のワークブックに新しい空のシートを追加します。

add_excel_sheet(file_path="/path/to/file.xlsx", sheet_name="Q3", position=0)

`update_excel_cells`

座標を指定して個々のセルの値を設定します。= で始まる値は数式として書き込まれます。

update_excel_cells(
    file_path="/path/to/file.xlsx",
    updates={"A1": "Title", "B2": 42, "C2": "=SUM(B2:B10)"},
    sheet_name="Data"             # optional, defaults to first sheet
)

注：新しく書き込んだ数式は、ファイルを Excel で開くまで計算結果が表示されません。結合された範囲に書き込む場合は、左上のアンカーセルを指定してください。

`write_excel_rows`

表形式のデータを、1 回の呼び出しで長方形の範囲に書き込みます。

write_excel_rows(
    file_path="/path/to/file.xlsx",
    rows=[["Item", "Qty"], ["Widget", 4], ["Gadget", 7]],
    sheet_name="Data",            # optional
    start_cell="A1"               # optional
)

`insert_excel_image`

ローカルの画像ファイルを、セルを基準位置としてワークブックに挿入します。

insert_excel_image(
    file_path="/path/to/file.xlsx",
    image_path="/path/to/chart.png",
    cell="B2",
    sheet_name="Report",          # optional
    width=480, height=320         # optional display size in px
)

`format_excel_cells`

範囲のスタイルを設定します。フォント、色、罫線、配置、表示形式を指定できます。渡した属性のみが変更され、既存のスタイルは保持されます。

format_excel_cells(
    file_path="/path/to/file.xlsx",
    cell_range="A1:D1",
    bold=True,
    font_color="FFFFFF",
    fill_color="4472C4",
    horizontal_align="center",
    border_style="thin",          # thin | medium | thick | double | dashed | dotted
    border_edges="all",           # "all" or "outline" (outer edge of range only)
    number_format="#,##0.00"      # any Excel format code
)

`set_excel_column_widths`

列幅を手動で設定するか、内容に合わせて自動調整します。

set_excel_column_widths(
    file_path="/path/to/file.xlsx",
    widths={"A": 12, "B": 35},    # explicit widths (skipped by auto-fit)
    auto_fit=True,                # size remaining columns to content
    max_width=60,                 # cap for auto-fit
    wrap_overflow=True            # wrap cells longer than the cap
)

自動調整では、全角の CJK 文字（日本語）は 2 単位として数えます。max_width を超える長さのセルは、列幅を広げる代わりに折り返しが有効になります。ファイルを開くと、Excel が行の高さを自動調整します。

すべての書き込みツールはアトミック保存を使用します。ワークブックはいったん一時ファイルに書き込まれてから置き換えられるため、保存に失敗しても元のファイルが破損することはありません。.xlsm のマクロは保持されます。openpyxl の既知の制限として、ピボットテーブルと一部の複雑なグラフ機能は、再保存時に保持されません。

⚙️ 動作の仕組み

アーキテクチャ

Your AI Client (Claude, Cursor, etc.)
       │
       │ stdio (JSON-RPC)
       ▼
┌─────────────────────────────┐
│     Excel Vision MCP        │
│                             │
│  ┌───────────────────────┐  │
│  │   openpyxl            │  │──→ Cell data, formulas, merged cells
│  │   (Excel parser)      │  │
│  └───────────────────────┘  │
│                             │
│  ┌───────────────────────┐  │
│  │ openpyxl-image-loader │  │──→ Images with cell positions
│  │ + zipfile (fallback)  │  │
│  └───────────────────────┘  │
│                             │
│  ┌───────────────────────┐  │
│  │   Pillow              │  │──→ Resize, optimize, base64 encode
│  │   (image processing)  │  │
│  └───────────────────────┘  │
└─────────────────────────────┘
       │
       │ TextContent + ImageContent
       ▼
  AI sees text AND images

データフローとプライバシー

ファイルはお使いのマシンに保存されたままです。 サーバーは stdio 経由でローカル実行されます。ネットワークリクエストやアップロード、クラウド利用はありません。
読み取りツールがファイルを変更することはありません。 画像処理はすべてメモリ内（BytesIO バッファ）で行われます。書き込みツールが変更するのは、指定したファイルのみです。アトミック保存（一時ファイルへの書き込みと置き換え）を使用するため、ワークブックが中途半端な状態で残ることはありません。
ディレクトリのサンドボックスは任意で設定できます。 EXCEL_VISION_MCP_ALLOWED_DIRS（パス区切り文字で区切ったリスト）を設定すると、サーバーが読み書きできるディレクトリを制限できます。未設定の場合、制限はありません。
メモリは自動的に解放されます。 リクエストごとに、Python のガベージコレクターがすべてのバッファを解放します。

画像処理パイプライン

Original image in .xlsx (e.g., 2048×1536px PNG)
  ↓ Extract from ZIP archive / drawing layer
  ↓ Resize to fit max dimensions (default 1024px)
  ↓ Compress (JPEG 80% / PNG optimized)
  ↓ Base64 encode
  → ImageContent returned to AI client (~100-300KB per image)

📋 対応形式

形式	状態	備考
`.xlsx`	✅ 完全対応	Excel 2007 以降の Open XML
`.xlsm`	✅ 完全対応	マクロ有効ワークブック
`.xls`	❌ 非対応	旧形式の Excel 97-2003
`.csv`	❌ 非対応	CSV 専用ツールを使用してください

画像の種類

画像の種類	セルとのマッピング	アーカイブからの抽出
PNG	✅	✅
JPEG	✅	✅
GIF	✅	✅
BMP	✅	✅
TIFF	⚠️ 一部対応	✅
EMF/WMF	❌	✅
`=IMAGE()` 数式	❌	❌
コメント内の画像	❌	❌

📊 パフォーマンス

実際のエンタープライズ向け Excel ファイルでテスト済みです（macOS、Apple Silicon）。

ファイル	サイズ	シート数	抽出した画像	時間
要件定義書 A	4.5 MB	12	24	2.4s
要件定義書 B	5.0 MB	6	18	2.4s
要件定義書 C	10.7 MB	6	13	1.5s
マスター仕様書	16.0 MB	12	40	4.4s

❓ よくある質問

.xls ファイルから画像を抽出できないのはなぜですか？

.xls は旧式のバイナリ形式（Excel 97-2003）です。.xlsx（ZIP ベースの Open XML）とは内部構造（BIFF）がまったく異なります。使用しているライブラリ（openpyxl、openpyxl-image-loader）は、最新の Open XML 形式のみをサポートしています。.xls ファイルをお持ちの場合は、まず Excel または LibreOffice を使って .xlsx に変換してください。

一部の画像が「孤立」と表示されるのはなぜですか？

主な抽出方法（openpyxl-image-loader）では、画像を特定のセルに対応付けますが、標準の描画レイヤーにアンカーされていない画像を見落とす場合があります。フォールバックのアーカイブスキャナーは、xl/media/ ディレクトリからこうした「孤立」画像を検出します。孤立画像のセル位置メタデータはありませんが、すべての画像を取得できます。

ビジョンに対応していないモデルでも使えますか？

はい。テキストデータの抽出は、どのモデルでも問題なく動作します。画像抽出では引き続き ImageContent が返されますが、テキスト専用モデルは画像データを無視します。エラーは発生しません。

データは安全ですか？

はい。サーバーは stdio トランスポートを介して、すべてローカルマシン上で動作します。ネットワーク経由でデータが送信されることも、ファイルがどこかにアップロードされることもありません。読み取りツールがファイルを変更することはありません。書き込みツールは、アトミック保存を使用して、明示的に指定したファイルのみを変更するため、書き込みに失敗してもファイルが破損することはありません。また、EXCEL_VISION_MCP_ALLOWED_DIRS 環境変数を使って、サーバーのアクセス範囲を特定のディレクトリに制限することもできます。

非常に大きなファイル（100MB 以上）はどのように扱えばよいですか？

サーバーはデータの反復処理に read_only モードを使用し、画像を一度に 1 枚ずつメモリ内で処理します。極端に大きなファイルの場合は、メモリ使用量を制御するため、read_full_content の代わりにページネーション（start_row + max_rows）を指定して read_excel_data を使用してください。

🗺️ ロードマップ

書き込みサポート — ワークブックの作成、セルの更新、数式の書き込み、画像の挿入 (v1.1.0)
書式を考慮した読み取り — 太字、取り消し線、ハイライト、色、非表示コンテンツの処理 (v1.2.0)
数式の評価 — 数式と計算結果をあわせて表示
CSV/TSV サポート — その他の表形式への対応
条件付き書式 — 書式ルールの抽出
グラフの抽出 — グラフを画像としてレンダリング

🤝 コントリビューション

コントリビューションを歓迎します！変更したい内容について話し合うため、まずイシューを作成してください。

git clone https://github.com/VOYAGER-Inc/excel-vision-mcp.git
cd excel-vision-mcp
uv sync
uv run pytest  # Run the test suite

📄 ライセンス

MIT — ご自由にお使いください。

テキストだけでなく、全体像を見る必要がある AI エージェントのために作られました。

役に立ったら、このリポジトリに ⭐ を付けてください！

Markdown 対応

ログインしてコメント

基本情報

作者: VOYAGER-Inc
言語: python
バージョン: 1.2.1
トランスポート: stdio
掲載日: 2026年7月30日
最終更新: 13 週間前
公式 Registry: io.github.VOYAGER-Inc/excel-vision-mcp

問題を報告

MCP は初めてですか？

プロトコルの概要から最初のサーバーの導入まで、よくある疑問にまとめて答えます。

入門ガイドを読む

AI アプリケーションが外部のツールやデータソースに統一的な方法で接続するためのオープンなプロトコルです。クライアントはモデルとの対話を担い、MCP サーバーはツール・リソース・プロンプトテンプレートを提供します。標準メッセージでやり取りするため、1 つのサーバーを複数のクライアントで再利用できます。

excel-vision-mcp

excel-vision-mcp について

主な機能

活用シーン

MCP 対応

設定

ツール

詳細

📊 Excel Vision MCP

AI はスプレッドシートを読み取れます。しかし、セル B12 の図は見えません。

🤔 問題点

✨ 主な機能

画像抽出 — ここが違います

👀 実際の動作を見る

🚀 クイックスタート

uvx でインストール（推奨）

pip でインストール

ソースからインストール

Docker で実行

🔧 設定

Claude Desktop

Cursor

Windsurf / VS Code (Copilot)

Antigravity IDE

ファイルアクセスの制限（任意）

🛠️ 利用可能なツール

list_sheets

read_excel_data

extract_images

read_full_content ⭐

非表示の行と列

get_workbook_overview

search_excel

create_excel_file

add_excel_sheet

update_excel_cells

write_excel_rows

insert_excel_image

format_excel_cells

set_excel_column_widths