ExcelMCP

Eine Live-Excel-Intelligenzschicht für KI-Agenten. Richten Sie es auf einen OneDrive-Ordner aus und Ihr Agent kann Fragen zu diesen Tabellenkalkulationen in einfachem Englisch stellen – zu den Zahlen, die gerade darin stehen.

Das Problem, das dies löst

Die meisten Tabellenkalkulations-Integrationen funktionieren, indem sie Ihre Daten woanders hin kopieren. Sie erfassen die Arbeitsmappe, teilen sie auf, betten die Zellenwerte ein und speichern das Ganze in einer Vektordatenbank. Von diesem Moment an beantwortet Ihr Agent Fragen zu einer Momentaufnahme. Jemand aktualisiert um 9 Uhr das Inventarblatt und der Agent zitiert immer noch die Zahlen von Dienstag.

ExcelMCP teilt das Problem in zwei Teile.

Die Struktur wird zwischengespeichert. Dateinamen, Blattnamen, Spaltenüberschriften, wo die Kopfzeile beginnt, welche Spalten Daten enthalten, wie Blätter zueinander in Beziehung stehen – plus eine kleine Stichprobe unterschiedlicher Bezeichnungen pro Spalte mit geringer Kardinalität, was das Routing über hundert fast identische Blätter hinweg ermöglicht. Dies ändert sich selten, ist billig zu speichern und ist das, was der Agent braucht, um zu wissen, wonach er fragen muss. (Die Stichprobenbezeichnungen sind der einzige Ort, an dem die Struktur Werte berührt; die genaue Grenze wird in Was landet auf der Festplatte erläutert.)

Daten werden nie zwischengespeichert. Jeder Tool-Aufruf, der eine Zahl zurückgibt, geht an die Microsoft Graph API und holt sie live ab. Es gibt keinen Daten-Cache, der veralten könnte, keinen Synchronisationsjob, der zurückfallen könnte, und keine Antwort, die jemals von der Festplatte bedient wird.

Jede Antwort enthält einen metadata.fetched_at-Zeitstempel und ein is_cached: false-Flag, damit das Modell im Band sehen kann, dass es frische Daten betrachtet.

Related MCP server: Microsoft 365 MCP Server

So funktioniert es

Eine Frage in natürlicher Sprache wird eingebettet, per Kosinusähnlichkeit mit den Blattbeschreibungen abgeglichen und dann durch lexikalische Überlappung mit Spaltennamen und Stichprobenwerten neu bewertet – das hält das Routing sinnvoll, wenn zwanzig Arbeitsmappen ein Schema teilen. Diese Blätter, und nur diese, werden live abgerufen. Filterung und Aggregation erfolgen dann in pandas auf dem frisch abgerufenen DataFrame. Einwertige Fragen überspringen die Zeilenpipeline vollständig: lookup liest eine Schlüsselspalte und eine Zeile und gibt die Zelle mit ihrer Herkunft zurück.

Voraussetzungen

• Python 3.10 oder neuer

• Ein Microsoft 365-Konto mit OneDrive

• uv oder einfaches pip, wenn Sie bevorzugen

Installation

Aus dem Repository-Stammverzeichnis:

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

Oder direkt aus dem Quellcode installieren, ohne zu bauen:

pip install .

Es gibt keinen Compiler-Schritt und keine native Erweiterung, die gebaut werden muss. Die Vektorsuche verwendet einen NumPy-Kosinus-Scan anstelle von hnswlib, speziell damit pip install auf einem Rechner ohne C++-Toolchain funktioniert.

Einrichtung

Führen Sie den Assistenten einmal aus:

excelmcp-setup

Er führt durch vier Schritte:

1. Microsoft-Gerätefluss-Anmeldung. Sie erhalten einen Code, den Sie im Browser einfügen, der Token-Cache landet in ~/.excelmcp/token.json mit 0600-Berechtigungen.

2. Welcher OneDrive-Ordner indiziert werden soll, z. B. /ERP.

3. Ein Scan jeder .xlsx in diesem Ordner, um den Strukturgraphen und die Einbettungen zu erstellen.

4. Erkennung der bereits auf Ihrem Rechner installierten KI-Agenten und ein schriftlicher Konfigurationseintrag für diejenigen, die Sie auswählen.

Agenten, die es automatisch konfigurieren kann

Vorhandene Konfigurationsdateien werden gesichert, bevor sie geändert werden. Wenn Ihr Agent nicht auf der Liste steht, gibt der Assistent den genauen JSON- oder TOML-Block aus, den Sie selbst einfügen können.

Weitere Assistentenbefehle

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

Für den Agenten verfügbare Tools

Die beiden Struktur-Tools sind kostenlos und sofort, da sie den lokalen Graphen lesen. Alles, was mit live markiert ist, geht bei jedem einzelnen Aufruf an die API.

Verwendung

Sobald der Server registriert ist, sprechen Sie meist einfach normal mit Ihrem Agenten. Im Hintergrund führt er Aufrufe wie diese durch.

Zuerst orientieren. Der Agent sollte dies immer tun, bevor er einen Spaltennamen errät, da keine zwei Unternehmen Dinge gleich benennen:

get_workspace_graph(folder_path="/ERP")

Eine Frage stellen, ohne zu wissen, wo die Antwort lebt:

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

Ein bekanntes Blatt filtern:

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

Unterstützte Bedingungsoperatoren, alle mit UND verknüpft:

Ein Spaltenname oder Operator, der nicht existiert, erzeugt einen Fehler, anstatt stillschweigend null Zeilen zurückzugeben – das ist der Fehlermodus, der dazu führt, dass ein Agent selbstbewusst die falsche Sache meldet. Wenn Bedingungen legitim nichts finden, enthält die Antwort zero_match_diagnostics – was jede Bedingung für sich allein gefunden hat, plus bis zu zwanzig tatsächlich in der betreffenden Spalte vorhandene Werte – damit eine knapp verfehlte Übereinstimmung korrigiert wird, anstatt als „keine Daten" gemeldet zu werden.

Nach einer einzelnen Zahl in einem Aufruf fragen:

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

Die Antwort kommt mit Herkunft – Datei, Blatt, Zelladresse, die übereinstimmende Zeile – und einem Konfidenzfeld. Mehrere übereinstimmende Zeilen geben ambiguous mit jeder Zeile zurück; Blätter, die widersprechen, geben conflict mit jeder Version und keinem Wert zurück; ein falsch geschriebener Schlüssel gibt unscharfe Vorschläge zurück. Das Tool gibt niemals eine bloße Zahl zurück.

Gruppieren und reduzieren innerhalb einer Datei:

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

Dasselbe Blatt über alle Dateien im Arbeitsbereich summieren:

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

cross_file_aggregate gibt eine Aufschlüsselung pro Datei zusammen mit der Gesamtsumme zurück, plus skipped_files, wenn eine Datei nicht gelesen werden konnte, und unmatched_files – mit did_you_mean-Kandidaten – für jede Datei, die nicht den genauen Blattnamen enthält. Auf diese Weise ist eine partielle Summe sichtbar partiell, anstatt stillschweigend falsch zu sein, einschließlich des Falls, wenn das Blatt in einigen Dateien Sales und in anderen Sales 2024 heißt. Überprüfen Sie sheet_name_variants in get_workspace_graph, bevor Sie aggregieren, um diese Fragmentierung im Voraus zu sehen.

Agenten-Spielbuch

Den Server zu installieren ist die einfache Hälfte. Der Ordner agents/ deckt die andere Hälfte ab: wie man einen Agenten, der diese Tools hat, auffordert, wie man ihn in jeden Host einbindet und was zu automatisieren ist, sobald es funktioniert.

Im Server integrierte Schutzmaßnahmen

Der Server liefert eine Reihe von Betriebsregeln in seinen MCP-Anweisungen mit, die das Host-Modell liest, bevor es seinen ersten Aufruf tätigt. Sie existieren, weil dies die spezifischen Arten sind, wie ein LLM Tabellenkalkulationsfragen falsch beantwortet:

• Gehen Sie niemals von einem Dateinamen, Blattnamen oder Spaltennamen aus. Entdecken Sie ihn aus dem Graphen.

• Addieren Sie niemals dateiübergreifende Zahlen im Kopf. Rufen Sie cross_file_aggregate auf und lassen Sie das Tool die Arbeit machen.

• Greifen Sie niemals auf openpyxl, pandas.read_excel oder das lokale Dateisystem zurück. Die Dateien befinden sich nicht auf diesem Rechner.

• Summieren Sie niemals eine Mengenspalte in transaktionsartigen Daten roh – verwenden Sie derive mit den ausgeschriebenen Transaktionstypen.

• Datumsangaben kommen als ISO-8601-Zeichenketten an, die bereits vom Server aus Seriennummern konvertiert wurden. Führen Sie niemals manuelle Serienarithmetik durch.

• Rufen Sie für eine einzelne Zahl lookup auf und zitieren Sie die zurückgegebene Herkunft; zeigen Sie die Ergebnisse ambiguous und conflict an, anstatt einen Wert auszuwählen.

• Überprüfen Sie die Felder truncated und total_matched, bevor Sie ein Ergebnis als vollständig bezeichnen.

Hosts, die Serveranweisungen ignorieren, und benutzerdefinierte Agents, die Sie selbst erstellen, benötigen diese Angabe in ihrem eigenen Prompt. Siehe agents/system-prompt.md.

Konfiguration

Die integrierte Client-ID ist ein öffentlicher Client, der für den Gerätecode-Flow verwendet wird. Sie trägt kein Geheimnis, ist absichtlich in jeder Authentifizierungsanfrage sichtbar und kann bedenkenlos in diesem Repository vorhanden sein. Tauschen Sie sie gegen Ihre eigene App-Registrierung aus, wenn der Zustimmungsbildschirm den Namen Ihrer Organisation tragen soll.

Was auf der Festplatte landet

~/.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.

Die ehrliche Version der No-Cache-Behauptung, Stand 0.3.0. Keine Zeile Ihrer Daten, kein Zellraster und kein abfragbarer Wert wird auf der Festplatte gespeichert – jede Antwort wird immer aus einem Live-Abruf bedient. Es gibt eine bewusste Ausnahme: graph.json speichert Stichprobenwerte, bis zu 50 unterschiedliche Textbezeichnungen pro Spalte mit niedriger Kardinalität (Kundennamen, Status, Materialnamen, Einheiten), die zum Scan-Zeitpunkt erfasst werden. Sie existieren, damit hundert strukturell identische Blätter bei der Weiterleitung einer Frage unterscheidbar sind, damit lookup finden kann, welches Blatt "BESTEX" enthält, ohne alles herunterzuladen, und damit Beziehungen aus Wertüberlappungen abgeleitet werden können, anstatt aus Spaltennamen angenommen zu werden. Sie sind Routing-Nachweise, kein Daten-Cache: Nichts beantwortet jemals eine Frage aus ihnen, und ein Arbeitsbereichs-Scan aktualisiert sie vollständig. Der Graph speichert auch einen blattspezifischen Struktur-Fingerabdruck (Kopfzeilenspalten und verwendeter Bereich) ausschließlich zur Erkennung von Abweichungen, und – neu in 0.3.0 – eine Regionenkarte: die Zeilenspannen jedes Tabellenkörpers auf einem Blatt, abgeleitet aus den Bereichen, auf die die eigenen SUM/COUNT/AVERAGE-Formeln des Blattes verweisen, plus die Adressen, die jede blattübergreifende Formel liest. Dies sind Zeilennummern und Zelladressen, keine Inhalte; es wird kein Wert gelesen, um sie zu erzeugen. Das label einer Region, sofern vorhanden, ist die zweite bewusste Ausnahme neben den Stichprobenwerten: ein paar Worte, die aus der Abschnittsbanner-Zelle unmittelbar über einer Region gelesen werden ("NAPHTHALENE", "OLEUM 65%"), aufbewahrt, damit das Modell benennen kann, welche Tabelle es meint, anstatt aus Zeilennummern zu raten. Es handelt sich um strukturelle Metadaten, die das Layout des Blattes beschreiben, nicht um Zeilendaten – dieselbe Unterscheidung, die Stichprobenwerte bereits ziehen. Wenn Ihnen das alles zu viel auf der Festplatte ist, scannen Sie diesen Ordner nicht; wenn Sie die Grenze überprüfen möchten, ist graph.json klein und lesbar, also schauen Sie nach.

Unter Windows schaltet os.chmod nur das Read-Only-Bit um, daher ist der Modus 0600 dort ein Best-Effort-Versuch, und der eigentliche Schutz ist die standardmäßige benutzerspezifische ACL auf %USERPROFILE%. Unter macOS und Linux wird der Modus auf die temporäre Datei angewendet, bevor Inhalt geschrieben wird, sodass das Token nie kurzzeitig weltweit lesbar ist.

Tests

# 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

Die Integrationssuite überspringt sich selbst, wenn EXCELMCP_TEST_FOLDER nicht gesetzt ist, sodass ein einfacher pytest-Lauf offline bleibt.

Projektstruktur

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

Mitwirken

Issues und Pull-Requests sind willkommen. Wenn Sie Unterstützung für einen weiteren Agenten hinzufügen, ist agents.py die einzige Datei, die Sie bearbeiten müssen: Fügen Sie ein AgentSpec mit dem Konfigurationspfad, der Eintragsform und einem Erkennungshinweis hinzu.

Lizenz

MIT. Siehe LICENSE.