ExcelMCP

AIエージェントのための生きたExcelインテリジェンスレイヤー。 OneDriveフォルダを指定するだけで、エージェントが現在の数値に基づいて、それらのスプレッドシートについて平易な英語で質問できるようになります。

これが解決する問題

ほとんどのスプレッドシート連携は、データを別の場所にコピーすることで機能します。ワークブックを取り込み、チャンク化し、セルの値を埋め込み、全体をベクターデータベースに保存します。その瞬間から、エージェントはスナップショットに関する質問に答えることになります。誰かが午前9時に在庫シートを更新しても、エージェントは火曜日の数値を引用し続けます。

ExcelMCPは問題を2つに分割します。

構造はキャッシュされます。 ファイル名、シート名、列ヘッダー、ヘッダー行の開始位置、日付を保持する列、シート同士の関係、そして低カーディナリティ列ごとの個別ラベルの小さなサンプル — これが、何百ものほぼ同一のシート間でのルーティングを意味のあるものにします。これらはめったに変更されず、保存コストも安く、エージェントが何を要求すべきかを知るために必要なものです。（サンプリングされたラベルは、構造が値に触れる唯一の場所です。正確な境界はディスクに保存されるものに詳述されています。）

データは決してキャッシュされません。 数値を返すすべてのツールコールは、Microsoft Graph APIにアクセスし、ライブでデータを取得します。古くなるデータキャッシュも、遅れる同期ジョブも、ディスクから提供される回答もありません。

すべてのレスポンスには、metadata.fetched_atタイムスタンプとis_cached: falseフラグが含まれ、モデルが帯域内で最新データを見ていることを認識できるようにします。

Related MCP server: Microsoft 365 MCP Server

仕組み

自然言語の質問が埋め込まれ、コサイン類似度によってシートの説明と照合され、次に列名とサンプリングされた値との字句的な重複によって再ランク付けされます。これにより、20のワークブックが1つのスキーマを共有する場合でも、ルーティングが意味を保ちます。これらのシート、そしてそれらのシートのみがライブでフェッチされます。フィルタリングと集計は、新しくフェッチされたフレームに対してpandasで行われます。単一値の質問は行パイプラインを完全にスキップします。lookupは1つのキー列と1つの行を読み取り、その出所とともにセルを返します。

要件

• Python 3.10 以降

• OneDriveを使用するMicrosoft 365アカウント

• uv、または必要に応じて通常のpip

インストール

リポジトリルートから:

git clone https://github.com/Karunya-Muddana/ExcelMCP.git
cd ExcelMCP

uv sync      # install dependencies
uv build     # build the wheel
pip install dist/excelmcp-0.3.0-py3-none-any.whl

または、ビルドせずにソースから直接インストール:

pip install .

コンパイラのステップやビルドする必要のあるネイティブ拡張はありません。ベクトル検索はhnswlibではなくNumPyのコサインスキャンで実行されるため、C++ツールチェーンのないマシンでもpip installが機能します。

セットアップ

ウィザードを一度実行します:

excelmcp-setup

以下の4つの手順を実行します:

1. Microsoftデバイスフローサインイン。コードが発行され、ブラウザに貼り付けると、トークンキャッシュが0600パーミッションで~/.excelmcp/token.jsonに保存されます。

2. インデックスを作成するOneDriveフォルダ（例: /ERP）。

3. そのフォルダ内のすべての.xlsxをスキャンして、構造グラフと埋め込みを構築します。

4. マシンに既にインストールされているAIエージェントを検出し、選択したエージェントの設定エントリを書き込みます。

自動設定可能なエージェント

既存の設定ファイルは変更前にバックアップされます。エージェントがリストにない場合、ウィザードは自分で貼り付けるための正確なJSONまたはTOMLブロックを出力します。

その他のウィザードコマンド

excelmcp-setup list-agents           # show what was detected
excelmcp-setup install --only cursor # register with one agent, skip the rescan
excelmcp-setup doctor                # diagnose a broken install
excelmcp-setup uninstall             # remove ExcelMCP from every agent config
excelmcp-setup --folder /ERP --yes   # fully non-interactive
excelmcp-setup --dry-run             # print the changes, write nothing

エージェントに公開されるツール

2つの構造ツールはローカルグラフを読み取るため、無料で即時応答です。ライブとマークされたものは、呼び出しのたびにAPIにアクセスします。

使用方法

サーバーが登録されると、通常通りエージェントと会話するだけです。内部的には、以下のような呼び出しが行われます。

まずは方向性を確認。エージェントは列名を推測する前に常にこれを行うべきです。同じ名前の会社は2つとないからです:

get_workspace_graph(folder_path="/ERP")

答えがどこにあるかわからずに質問する:

query("what are the top 10 products by sales value", folder_path="/ERP")

既知のシートをフィルタリングする:

filter_sheet(
    file_name="Inventory.xlsx",
    sheet="Stock",
    conditions={"Status": "Low", "Quantity": "<50"},
    folder_path="/ERP",
    sort_by="Quantity",
    limit=100,
)

サポートされている条件演算子（すべてAND結合）:

存在しない列名や演算子は、静かに0行を返すのではなくエラーを発生させます。これは、エージェントが誤った情報を自信を持って報告する原因となる障害モードです。条件が正当に何も一致しない場合、レスポンスにはzero_match_diagnosticsが含まれます — 各条件が単独で何に一致したか、問題の列に実際に存在する最大20個の値 — これにより、ニアミスが「データなし」と報告される代わりに修正されます。

1回の呼び出しで単一の数値を尋ねる:

lookup(query="contracted rate for Titanium Dioxide under the BESTEX contract",
       folder_path="/Contracts")

回答は出所（ファイル、シート、セルアドレス、一致した行）と信頼度フィールドとともに返されます。複数の一致行がある場合はambiguousとすべての行が返され、シート間で矛盾がある場合はconflictとすべてのバージョンが値なしで返され、キーのスペルミスはあいまいな提案を返します。このツールは裸の数値を返すことはありません。

1つのファイル内でグループ化して集約する:

aggregate(
    file_name="Sales.xlsx",
    sheet="Q1",
    group_by="Region",
    value_col="Revenue",
    operation="sum",
    folder_path="/ERP",
)

ワークスペース内のすべてのファイルで同じシートを合計する:

cross_file_aggregate(
    sheet="Q1",
    value_col="Revenue",
    operation="sum",
    folder_path="/ERP",
    conditions={"Status": "Closed"},
)

cross_file_aggregateは、合計とともにファイルごとの内訳を返し、ファイルが読み取れなかった場合はskipped_filesを、正確なシート名を含まないすべてのファイルに対してdid_you_mean候補を含むunmatched_filesを返します。これにより、部分的な合計が静かに間違っているのではなく、明らかに部分的であることがわかります。これは、一部のファイルでシート名がSalesであり、他のファイルでSales 2024である場合も含みます。集計する前にget_workspace_graphでsheet_name_variantsを確認して、その断片化を事前に把握してください。

エージェントプレイブック

サーバーのインストールは簡単な半分です。agents/フォルダは残りの半分をカバーしています: これらのツールを持つエージェントにプロンプトを与える方法、各ホストに配線する方法、そして動作した後に何を自動化するか。

サーバーに組み込まれたガードレール

サーバーには、MCPインストラクションとして一連の運用ルールが同梱されており、ホストモデルが最初の呼び出しを行う前に読み取ります。これらは、LLMがスプレッドシートの質問を間違える具体的な方法に対処するために存在します。

• ファイル名、シート名、列名を決して推測しない。グラフから発見すること。

• ファイルをまたいだ数値を頭の中で合計しない。cross_file_aggregateを呼び出してツールに任せること。

• openpyxl、pandas.read_excel、またはローカルファイルシステムに決してアクセスしない。ファイルはこのマシン上にありません。

• トランザクション形式のデータで数量列を生のまま合計しない。deriveを使用し、トランザクションタイプを明示的に指定すること。

• 日付列はISO-8601文字列として到着し、サーバーによってシリアル値から変換済みです。シリアル演算を手動で行わないこと。

• 単一の数値の場合はlookupを呼び出し、それが返す出典情報を引用すること。ambiguousおよびconflictの結果を表示し、値を自分で選ばないこと。

• 結果が完全であると主張する前に、truncatedおよびtotal_matchedフィールドを確認すること。

サーバーインストラクションを無視するホスト、および自分で構築するカスタムエージェントについては、この内容を独自のプロンプトに明記する必要があります。agents/system-prompt.mdを参照してください。

構成

組み込みのクライアントIDは、デバイスコードフローに使用されるパブリッククライアントです。シークレットは含まれず、設計上すべての認証リクエストで可視であり、このリポジトリに含めても安全です。同意画面に組織名を表示したい場合は、独自のアプリ登録に置き換えてください。

ディスクに保存されるもの

~/.excelmcp/
  token.json           MSAL token cache. Auth material only, written 0600.
  graph.json           Structure graph: item IDs, sheet names, column headers,
                       used-range dimensions, date column types, per-sheet
                       table regions, inferred and formula-declared
                       relationships — and sampled values (see below).
  vectors.npy          Embedded sheet descriptions for semantic routing.
  metadata.json        Labels and lexical terms tying each embedding to a sheet.
  relationships.yaml   Optional, written by you: declared join relationships.

バージョン0.3.0時点での、キャッシュなし主張の正直なバージョン。 データの行、セルグリッド、クエリ可能な値はディスクに保存されません。すべての回答は常にライブフェッチから提供されます。意図的な例外が1つあります：graph.jsonはサンプリングされた値を保存します。これは、低カーディナリティ列（クライアント名、ステータス、材料名、単位）あたり最大50個の異なるテキストラベルで、スキャン時に取得されます。これらは、質問をルーティングする際に構造的に同一のシートを区別できるようにするため、lookupがすべてをダウンロードせずにどのシートに「BESTEX」が含まれているかを特定できるようにするため、そして関係を列名から推測するのではなく値の重複から推測できるようにするために存在します。これらはルーティングの証拠であり、データキャッシュではありません。これらから質問に答えることは決してなく、ワークスペーススキャンによって完全に更新されます。グラフはまた、シートごとの構造フィンガープリント（ヘッダー列と使用範囲アドレス）を保存し、これはドリフト検出専用です。さらに、バージョン0.3.0ではリージョンマップも保存します：シート上の各テーブル本体の行スパン。これは、シート自体のSUM/COUNT/AVERAGE数式が参照する範囲と、シート間の数式が読み取るアドレスから導出されます。これらは行番号とセルアドレスであり、内容ではありません。値を読み取って生成されることはありません。存在する場合のリージョンのlabelは、サンプリングされた値に次ぐ2番目の意図的な例外です。リージョンのすぐ上のセクションバナーセルから読み取られた数語（「NAPHTHALENE」、「OLEUM 65%」）で、モデルが行番号から推測するのではなく、どのテーブルを指しているかを名前で指定できるように保持されます。これはシートのレイアウトを記述する構造メタデータであり、行データではありません。サンプリングされた値がすでに描いているのと同じ区別です。これらがディスクに保存される以上のことを望まない場合は、そのフォルダをスキャンしないでください。境界を確認したい場合は、graph.jsonは小さくて読み取り可能なので、見てみてください。

Windowsでは、os.chmodは読み取り専用ビットのみを切り替えるため、0600モードはそこでのベストエフォートであり、実際の保護は%USERPROFILE%のデフォルトのユーザーごとのACLです。macOSとLinuxでは、モードはコンテンツが書き込まれる前に一時ファイルに適用されるため、トークンが一時的にワールドリーダブルとして存在することはありません。

テスト

# offline unit tests, no network and no credentials required
pytest tests/test_unit.py

# live integration tests against a workspace you have already scanned, opt in
EXCELMCP_TEST_FOLDER=/ERP pytest tests/test_live_integration.py -v

統合テストスイートは、EXCELMCP_TEST_FOLDERが設定されていない場合に自分自身をスキップするため、プレーンなpytestの実行はオフラインのままです。

プロジェクトレイアウト

agents/           prompts, host guides, and schedulable routines
auth.py           MSAL device flow, token cache, proactive refresh
graph_client.py   Graph API wrapper, 429 backoff, shared concurrency gate
structure.py      Structure discovery, value sampling, relationship inference
embeddings.py     FastEmbed vectors, NumPy cosine search, lexical rerank
query_engine.py   Conditions, live fetch, aggregation, joins, derive
lookup.py         Single-cell lookup pipeline and get_cell
ranges.py         A1-notation range arithmetic
main.py           FastMCP tool definitions and server entry point
cli.py            Setup wizard, agent detection, config writing
agents.py         Per agent config formats and file locations
storage.py        Atomic writes, stderr logging, config directory handling

コントリビューション

Issueとプルリクエストは歓迎します。別のエージェントのサポートを追加する場合、agents.pyだけを触る必要があります。AgentSpecを設定パス、エントリ形状、検出ヒントとともに追加してください。

ライセンス

MIT。 LICENSEを参照してください。