excel-mcp

excel-mcp

AI エージェントが、実際の扱いにくい Excel ファイルを読み取れるようにします。 複数のシート、実際の表より上にあるタイトル行、セルの結合など、LLM が苦手とする処理に対応したMCP サーバーです。

スプレッドシートをプロンプトに貼り付けると、モデルはデータの開始位置や結合セルの意味を推測する必要があり、間違えることもよくあります。このサーバーは決定論的なコードでファイルを正しく読み取るため、値は正確で、モデルがセルの内容を捏造することもありません。

解決する問題

実際のスプレッドシートは、ほとんどの場合、セル A1 からきれいに始まるわけではありません。

A1:  Quarterly Sales Report 2024      <- title, not data
A2:  Generated by finance             <- note, not data
A3:  (blank)
A4:  Region | Product | Units         <- the actual header
A5:  North  | Widget  | 120
...

LLM にこれを読み取らせると、タイトルを列として扱うことがよくあります。read_table はヘッダーが 4 行目にあることを自動検出し、整ったレコードを返します。結合セル（複数の行にまたがる値）は下方向に補完されるため、行からカテゴリが失われません。

エージェントに提供するツール

ツール	機能
list_sheets(path)	ワークブック内のすべてのシートと、そのサイズを返します
preview_sheet(path, sheet, rows)	先頭の行をグリッド形式で返し、エージェントがレイアウトを確認できます
read_table(path, sheet)	実際のデータテーブルをレコードとして返します。誤っている可能性のある判断も報告します：header_source（明示指定／自動検出）、header_confidence、forward_filled_columns（読み取った値ではなく、結合セルから推定した値）
sheet_to_csv(path, sheet)	テーブルを整った CSV テキストとして返します

はじめに（Claude Desktop）

最も手軽な方法は、Claude Desktop のような MCP クライアントを使うことです。手順は 3 つです。

1. インストールします

pip install "excel-agent-mcp[mcp]"

2. クライアントの設定に追加します

Claude Desktop の設定ファイルは次の場所にあります。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

サーバーを追加します。

{
  "mcpServers": {
    "excel": { "command": "excel-agent-mcp" }
  }
}

3. Claude Desktop を再起動します。 ツールアイコンが表示され、サーバーが接続されたことを確認できます。

これで完了です。手元にある任意の .xlsx ファイルについて質問できます。

You:  What's in /Users/me/reports/sales.xlsx?

Agent (calls list_sheets, then read_table):
  The workbook has one sheet, "Q1". The table starts on row 4 (the rows above
  are a title). 3 rows: North/Widget/2400, South/Widget/3000, South/Gadget/2400.
  Total revenue 7800.

エージェントは推測ではなく実際のファイルを読み取るため、数値は正確です。

ファイルアクセスの制限： エージェントが指定したフォルダーの外にあるファイルを読み取れないようにするには、EXCEL_MCP_ALLOWED_DIR を設定します。SECURITY.md を参照してください。

他の MCP クライアントで使う

同じサーバーをどの MCP クライアントでも使用できます。設定だけが異なります。コマンドには excel-agent-mcp を指定します。

Cursor — ~/.cursor/mcp.json（グローバル）または .cursor/mcp.json（プロジェクトごと）。形式は Claude Desktop と同じで、ホットリロードされます（再起動不要）。

{ "mcpServers": { "excel": { "command": "excel-agent-mcp" } } }

VS Code / GitHub Copilot — .vscode/mcp.json。キーが異なる点（mcpServers ではなく servers）と、type が必須である点に注意してください。ツールを実行できるのは Copilot の エージェントモード のみです。

{ "servers": { "excel": { "type": "stdio", "command": "excel-agent-mcp" } } }

Windsurf — ~/.codeium/windsurf/mcp_config.json（存在しない場合は作成してください）。形式は Claude Desktop と同じです。

{ "mcpServers": { "excel": { "command": "excel-agent-mcp" } } }

Cline — VS Code の拡張機能にある MCP 設定パネルから追加します（コマンド：excel-agent-mcp）。

出力について

read_table はデータを返すだけでなく、どの程度確信できるかも示します。これにより、適切に解析できた結果を信頼しつつ、推測を確認できます。

{
  "columns": ["Region", "Product", "Revenue"],
  "rows": [ ... ],
  "header_row": 3,
  "header_source": "auto-detected",
  "header_confidence": 0.42,
  "forward_filled_columns": ["Region"]
}

• header_source — ヘッダー行を指定した場合は "explicit"、自動で推測した場合は "auto-detected" です。
• header_confidence — 自動検出されたヘッダーの確信度を 0..1 で示します。値が低い場合は判断が難しかったことを意味します。結果が不自然な場合は、header_row を明示的に指定してください。
• looks_clean + table_warnings — テーブル全体の判定を示します（ヘッダーの確信度が低い、名前のない列がある、ほとんど空のテーブルなどを警告します）。以下の列ごとのシグナルとは別の情報です。
• forward_filled_columns — 結合セルに由来する値を含む列です。値はセルごとに読み取ったものではなく、ブロックを埋めるために下方向へコピーした推定値なので、その点を踏まえて扱ってください。

誤っている可能性のある判断を隠して整った出力を返すのではなく、そうした判断を明示することが目的です。

通常の Python からも利用できます

from excel_mcp import reader

reader.list_sheets("report.xlsx")
reader.read_table("report.xlsx", "Sales")     # {'columns': [...], 'header_source': ..., ...}
reader.sheet_to_csv("report.xlsx", "Sales")

テスト

python -m unittest discover -s tests     # builds its own messy xlsx, runs anywhere

ライセンス

MIT