Ein Excel MCP Server stellt die Berechnungen einer Excel-Arbeitsmappe über das Model Context Protocol (MCP) als Tools für KI-Assistenten bereit. Bei SpreadAPI musst du dafür nichts installieren oder selbst betreiben: Jeder veröffentlichte Service hat eine eigene MCP-Adresse, an die Claude, ChatGPT oder ein anderer MCP-Client Eingabewerte schickt und von der er die Ergebnisse deiner Formeln zurückbekommt.
Dieser Leitfaden richtet sich an Entwickler, die wissen wollen, was auf dieser Verbindung tatsächlich passiert: was ein Assistent von einem Service sieht, wie du ihn einrichtest, wie die JSON-RPC-Nachrichten aussehen, was Tokens ändern und wo die Grenzen liegen. Alle Aussagen folgen dem Hilfe-Center von SpreadAPI. Die verlinkten Hilfe-Artikel sind auf Englisch.
Warum die Excel-Datei rechnen soll und nicht das Modell
Ein Sprachmodell versteht Fragen gut, exakte Arithmetik und Geschäftsregeln beherrscht es schlecht. Eine Preisliste mit Editionen, Mengenstaffeln und Rabattregeln ist genau die Art Aufgabe, die es nur fast richtig löst. SpreadAPI teilt die Arbeit deshalb auf:
- Der Assistent versteht die Frage und wählt die Eingabewerte.
- Deine Arbeitsmappe rechnet auf den Servern von SpreadAPI, mit deinen Formeln.
- Der Assistent gibt die Ergebnisse wieder, die er zurückbekommt.
Jeder Service sagt das dem Assistenten in seinen Anweisungen: Jedes Ergebnis wird vom Spreadsheet des Eigentümers berechnet, und der Assistent soll den Service für jede Zahl aufrufen, die er nennt, statt selbst zu rechnen oder zu schätzen. Die Regeln bleiben dort, wo sie ohnehin stehen: in der Excel-Datei. Ändern sie sich, passt du die Arbeitsmappe an und veröffentlichst neu.
Mehr dazu: AI safety and accuracy.
Zwei MCP-Adressen und wann du welche nimmst
SpreadAPI hat zwei MCP-Adressen. Welche passt, hängt davon ab, wem die KI gehört.
Die Konto-Adresse ist für deinen eigenen Assistenten:
https://spreadapi.io/mcpDu verbindest Claude oder ChatGPT einmal per Anmeldung mit deinem Konto. Der Assistent erreicht danach jeden Service, den du erlaubst, ohne Token, mit Tools wie list_services, describe_service und run_service. Gibst du ihm das Recht dazu, kann er auch neue Services aus einem Spreadsheet bauen, testen und veröffentlichen.
Die Service-Adresse ist für die Assistenten anderer, zum Beispiel eines Kunden:
https://spreadapi.io/api/mcp/service/{serviceId}Sie ist ein MCP-Server für genau einen Service. Wer sie einträgt, bekommt Tools, um mit diesem Service zu rechnen, und sonst nichts: keinen anderen Service, keine Arbeitsmappe, kein Konto.
Ein Agent, der keinen MCP-Server hinzufügen kann, nutzt stattdessen die Discovery-Adresse https://spreadapi.io/d/{serviceId}. Sie beschreibt den Service in Worten und JSON und rechnet über einfaches HTTP. Für eigenen Code gibt es außerdem die normale REST-API.
Mehr dazu: How AI assistants use a service.
Was der Assistent von einem Service sieht
Der Rest des Leitfadens betrachtet die Service-Adresse, denn dort kannst du jede Nachricht selbst nachlesen.
Drei Tools
spreadapi_calc: eine Berechnung. Eingabewerte hinein, Ergebnisse zurück.spreadapi_batch: 2 bis 20 Szenarien in einem Aufruf, um Varianten zu vergleichen.spreadapi_get_details: alle Eingaben und Ergebnisse im Detail, mit Beispielen und den Regeln für den Aufruf.
Alle drei lesen und rechnen nur. Sie tragen die Hinweise readOnlyHint: true und destructiveHint: false. Ein MCP-Client weiß damit, dass ein Aufruf nichts verändert und wiederholt werden kann.
Eingaben mit Typen und erlaubten Werten
Das Eingabeschema von spreadapi_calc führt jede Eingabe mit Typ, erlaubten Werten (enum), minimum, maximum, default und Beschreibung auf und nennt die Pflichtfelder. Diese Angaben stammen aus den Parameter-Einstellungen des Service, nicht aus einem Text, den du schreiben musst. Bei einer Prozent-Eingabe ergänzt SpreadAPI den Satz "Send a decimal: 0.05 for 5%." von selbst.
Ein Wert, der nicht erlaubt ist, wird abgelehnt, und die Antwort nennt die Eingabe und das, was erlaubt ist. Der Assistent kann den Aufruf dann korrigieren oder dem Nutzer sagen, was möglich ist.
Ergebnisse
Ein Ergebnis besteht aus drei Teilen:
outputs: eine Liste mitname,title,valueund, wenn die Zelle ein Zahlenformat hat,formatString.inputs: die Werte, wie das Spreadsheet sie verwendet hat. Hier schaust du zuerst nach, wenn ein Ergebnis seltsam aussieht.metadata:executionTimein Millisekunden undcached.
Das Briefing
Wenn sich der Assistent verbindet, enthält die Antwort auf initialize ein kurzes Briefing als Server-Anweisungen. Darin steht:
- Name und Beschreibung des Service;
- deine Hinweise, wann der Assistent ihn nutzen soll, gekennzeichnet als "Notes from the service owner";
- die Regeln für den Aufruf: jede Zahl mit dem Service berechnen, ein Aufruf verändert nichts, Prozente als Dezimalzahl senden, Varianten in einem Batch vergleichen, wie Ergebnisse gezeigt werden;
- falls du einen geschrieben hast, dein Wunsch, wie Ergebnisse dargestellt werden sollen;
- die Liste der Ergebnisse.
Diese Texte schreibst du im Service unter KI → Definition: Was der Service tut, Wann die KI ihn nutzen soll, So soll die KI antworten, Beispielfragen und je ein Satz pro Eingabe und Ergebnis. Der Darstellungswunsch ist eine Anweisung an das Modell, kein Layout. Assistenten halten sich meist daran, garantieren lässt es sich nicht.
Was er nicht sieht
Über die Service-Adresse sieht ein Assistent weder die Arbeitsmappe noch die Formeln, andere Zellen, andere Blätter oder deine übrigen Services. Er bekommt die Beschreibungen, die Eingaben mit ihren Grenzen, die Ergebnisse mit einem Beispielwert vom Zeitpunkt der Veröffentlichung und die Resultate seiner eigenen Aufrufe.
Ein Unterschied ist hier wichtig. Ein Assistent, der mit deinem eigenen Konto verbunden ist, sieht mehr, wenn du es erlaubst: Mit der Stufe Bearbeiten oder Vollzugriff kann er Blätter, Zellwerte und Formeln der Services lesen, die er erreichen darf, weil er sie zum Bauen braucht. Mit der Stufe Nutzen sieht er nur Beschreibungen, Eingaben, Ergebnisse und Resultate.
Mehr dazu: The MCP address of one service, Describe a service for AI, Write good descriptions.
Einrichtung Schritt für Schritt
Schritt 1: Aus der Arbeitsmappe einen Service machen
Melde dich auf spreadapi.io an und klicke auf Neuer Service. Wähle Arbeitsmappe importieren und zieh deine Excel-Datei hinein. Klicke im Reiter Konfiguration auf eine Zelle, die ein Aufrufer füllen soll, dann auf Als Parameter hinzufügen, und wiederhole das für jede Eingabe. Die Ergebniszellen fügst du genauso hinzu: Eine Zelle mit Formel wird als Ergebnis angelegt.
Schritt 2: Den Service für Assistenten beschreiben
Öffne KI → Definition und trag ein, was der Service tut, wann ein Assistent ihn nutzen soll und ein paar Beispielfragen. Gib jeder Eingabe und jedem Ergebnis einen Satz, der sagt, was der Wert bedeutet: die Einheit und worauf er sich bezieht. Typen, Wertebereiche und erlaubte Werte wiederholst du nicht, die werden automatisch mitgeliefert. Alles vorschlagen entwirft die leeren Felder für dich. Lies die Entwürfe, bevor du sie übernimmst.
Schritt 3: Speichern und veröffentlichen
Klicke auf Speichern, dann auf Veröffentlichen. Der Schritt ist nicht optional: Die MCP-Adresse eines Entwurfs antwortet nicht.
Schritt 4: Den eigenen Assistenten verbinden
Für Claude:
- Öffne in SpreadAPI aus der Service-Liste die Seite KI-Agenten und klicke auf KI verbinden.
- Wähle unter Mit Anmeldung · ohne Schlüssel den Eintrag Claude und kopiere die Adresse
https://spreadapi.io/mcp. - Füge in Claude einen eigenen Konnektor hinzu (in der englischen Oberfläche: Settings → Connectors → Add → Custom connector), gib ihm einen Namen und füge die Adresse ein. Wähle im nächsten Schritt "Sign in when needed".
- Claude öffnet SpreadAPI im Browser. Prüfe das angezeigte Konto und bestätige dann, was Claude tun darf.
- Zurück in SpreadAPI klickst du auf Fertig.
Die Zustimmungsseite startet mit Vollzugriff auf alle Services. Soll der Assistent nur rechnen, klicke auf Ändern, wähle Nutzen und beschränke ihn auf die Services, die er braucht.
Bei ChatGPT läuft es genauso, nur fügst du dort einen eigenen MCP-Server hinzu, trägst die Adresse ein und wählst OAuth als Authentifizierung.
Für Claude Code genügt ein Befehl, danach /mcp, spreadapi und "Authenticate":
claude mcp add --transport http spreadapi https://spreadapi.io/mcpAndere Clients verbindest du mit einem Schlüssel statt mit einer Anmeldung. Du legst ihn auf derselben Seite unter Mit Schlüssel an (Cursor, eigener Code, andere KI) und schickst ihn als Header Authorization: Bearer, gefolgt vom Schlüssel.
Zum Ausprobieren fragst du: "Welche Services habe ich bei SpreadAPI?"
Schritt 5: Oder einen einzelnen Service weitergeben
Öffne den Service, wähle KI → Verbinden und kopiere die Adresse unter Die KI von jemand anderem: die MCP-Adresse dieses Service. Die andere Person trägt sie in ihrem Assistenten als eigenen Konnektor ein. Bei einem öffentlichen Service wird keine Anmeldung verlangt.
Mehr dazu: Your first service, Connect Claude, Connect ChatGPT, The AI agents page.
Ein durchgerechnetes Beispiel: der Angebotsrechner
Nimm eine kleine Preis-Arbeitsmappe, veröffentlicht als Service "Quote calculator". Sie hat drei Eingaben und ein Ergebnis:
licenses: eine Zahl von 1 bis 500, Pflicht.edition: einer der Werte Basic, Pro, Enterprise, Pflicht.discount: ein Prozentwert von 0 bis 50 %, optional, Standard 0.total: das Ergebnis mit dem Titel "Total per month".
Die Preise sind eine Annahme dieses Beispiels: In unserer Beispiel-Arbeitsmappe kostet eine Pro-Lizenz 30 pro Monat. Deine Zahlen kommen aus deinen eigenen Formeln.
Tools auflisten
Die Service-Adresse spricht JSON-RPC 2.0 über HTTP POST mit den Methoden initialize, tools/list und tools/call. Bei einem öffentlichen Service kannst du sie selbst fragen:
curl -s -X POST \
"https://spreadapi.io/api/mcp/service/{serviceId}" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Die Antwort, gekürzt auf das erste Tool und ohne dessen Ausgabeschema:
{
"jsonrpc": "2.0",
"result": {
"tools": [
{
"name": "spreadapi_calc",
"description": "Use this when the user wants a single calculated result from \"Quote calculator\" — Calculates the monthly price of a subscription from the number of licences, the edition and the discount. …",
"inputSchema": {
"type": "object",
"properties": {
"inputs": {
"type": "object",
"properties": {
"licenses": {
"type": "number",
"description": "Number of people who get a licence, including admins.",
"minimum": 1,
"maximum": 500
},
"edition": {
"type": "string",
"description": "Edition of the product.",
"enum": ["Basic", "Pro", "Enterprise"]
},
"discount": {
"type": "number",
"description": "Discount on the list price agreed with the customer. Send a decimal: 0.05 for 5%.",
"minimum": 0,
"maximum": 0.5,
"default": 0
}
},
"required": ["licenses", "edition"]
}
},
"required": ["inputs"]
},
"annotations": {
"readOnlyHint": true,
"destructiveHint": false,
"openWorldHint": false
}
}
]
},
"id": 1
}Der erste Teil der Beschreibung wird erzeugt, der Satz nach dem Gedankenstrich ist der Text aus Was der Service tut. Die Beschreibungen der Eingaben sind die Sätze aus KI → Definition. Den Dezimal-Hinweis bei discount hat SpreadAPI ergänzt. Die Texte in diesem Beispiel sind englisch, weil der Service für englisch fragende Nutzer beschrieben wurde. Schreib deine in der Sprache, in der deine Nutzer fragen.
Rechnen
Ein Nutzer fragt: "Was kosten 25 Pro-Lizenzen mit 10 % Rabatt?" Der Assistent hat alle Pflichtwerte und ruft deshalb sofort auf:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "spreadapi_calc",
"arguments": {
"inputs": {
"licenses": 25,
"edition": "Pro",
"discount": 0.1
}
}
}
}Das Ergebnis kommt doppelt zurück: als JSON-Text in content und als Objekt in structuredContent. Gekürzt auf das Objekt und ohne executionTime:
{
"jsonrpc": "2.0",
"result": {
"structuredContent": {
"outputs": [
{
"name": "total",
"title": "Total per month",
"value": 675,
"formatString": "€#,##0.00"
}
],
"inputs": [
{ "name": "licenses", "title": "Licenses", "value": 25 },
{ "name": "edition", "title": "Edition", "value": "Pro" },
{ "name": "discount", "title": "Discount", "value": 0.1 }
],
"metadata": { "cached": false }
}
},
"id": 2
}Der Wert ist die rohe Zahl. formatString ist das Excel-Format der Zelle, damit der Assistent 675 als €675.00 zeigen kann. Bei den Namen der Eingaben spielt Groß- und Kleinschreibung keine Rolle.
Ein abgelehnter Wert
Fragt der Nutzer nach 25 "Platinum"-Lizenzen, wird der Aufruf abgelehnt. Das ist kein Protokollfehler, sondern ein normales Tool-Ergebnis mit isError: true, und sein Text nennt die Eingabe und das, was erlaubt ist:
Parameter validation failed: edition: Value "Platinum" is not allowed. Allowed values: Basic, Pro, EnterpriseWas der Assistent damit tun soll, steht im Briefing: dem Nutzer sagen, was erlaubt ist, statt für ihn einen anderen Wert zu wählen.
Varianten vergleichen
Bei "Pro oder Enterprise?" schickt der Assistent einen spreadapi_batch-Aufruf statt zwei einzelner. Die Argumente:
{
"scenarios": [
{
"label": "Pro",
"inputs": { "licenses": 25, "edition": "Pro" }
},
{
"label": "Enterprise",
"inputs": { "licenses": 25, "edition": "Enterprise" }
}
]
}Das Ergebnis enthält scenarios, jedes mit seinem label und outputs oder einem error, sowie metadata mit scenarioCount und successCount.
Dieselbe Berechnung über REST
Der Service ist für jeden Aufrufer derselbe. Dein eigener Code erreicht ihn ohne MCP:
curl -X POST \
"https://spreadapi.io/api/v1/services/{serviceId}/execute" \
-H "Content-Type: application/json" \
-d '{"inputs": {"licenses": 25, "edition": "Pro", "discount": 0.1}}'Mehr dazu: Call a service over the API, The API response.
Einen Service mit Tokens schützen
Ein veröffentlichter Service ist entweder öffentlich oder durch Tokens geschützt. Einen eigenen Schalter gibt es nicht: Ein Service mit mindestens einem Token ist geschützt, ein Service ohne Token ist öffentlich. Tokens legst du unter API → Zugriff mit Token erstellen an. Das erste Token schützt den Service sofort, ohne erneutes Veröffentlichen. Ein Token wird nur einmal angezeigt und gehört zu genau einem Service.
Was das für Assistenten heißt, hängt von der Adresse ab:
- Dein eigener Assistent an der Konto-Adresse braucht kein Service-Token, auch nicht für geschützte Services. Die Verbindung ist der Zugang. Du steuerst sie auf der Seite KI-Agenten: Stufe, Services, Ablaufdatum, Widerruf.
- Der Assistent eines anderen an der Service-Adresse bekommt von einem geschützten Service HTTP 401 "Authentication required". Ein Client, der Header setzen kann, schickt das Token als
Authorization: Bearer, gefolgt vom Token. Sonst startet der Client eine Anmeldung, und die Person fügt ein Token ein, das du erstellt hast. Diese Anmeldung gilt für diesen einen Service und hält 12 Stunden. - Die Anmeldung an einer geschützten Service-Adresse ist für ChatGPT gebaut. Für Claude nimmst du stattdessen eine Konto-Verbindung.
- Die Discovery-Adresse nimmt das Token als
?token=…, als Bearer-Header oder im POST-Body entgegen.
Zwei praktische Regeln aus dem Hilfe-Center. Gib jedem Kunden ein eigenes Token: So kannst du eines widerrufen, ohne die anderen zu treffen, und siehst im Reiter Nutzung, wer aufruft. Und denk daran, dass der Widerruf des letzten Tokens den Service sofort wieder öffentlich macht. Willst du ein Token ersetzen, lege zuerst das neue an.
Ein Unterschied für eigenen Code: Die REST-Adresse zum Ausführen beantwortet Token-Probleme mit HTTP 400 und einem Text in error, nicht mit 401.
Mehr dazu: Tokens and access.
Ehrliche Grenzen
- Aufrufe zählen. Eine Berechnung durch einen Assistenten zählt wie jeder andere Aufruf des Service, und in einem Batch zählt jedes Szenario. Sind die Aufrufe des Monats verbraucht, antworten die Tools mit "Monthly call limit reached" und sagen dem Assistenten, dass er es nicht erneut versuchen soll.
- Ein Batch fasst 2 bis 20 Szenarien.
- Ein Aufruf hat bis zu 30 Sekunden Zeit für die Antwort.
- Ratenlimits. Eine Konto-Verbindung macht höchstens 120 Aufrufe pro Minute. Ein Service nimmt höchstens 1.000 Aufrufe pro Minute an, alle Aufrufer zusammen.
- Nur Formeln. VBA-Makros laufen nicht, und Verknüpfungen zu anderen Arbeitsmappen werden nicht verfolgt. Logik, die in Makros steckt, musst du mit Formeln nachbauen.
- Änderungen brauchen eine neue Veröffentlichung. Aufrufer bekommen die veröffentlichte Version, bis du neu veröffentlichst. Ein Assistent, der die Tools schon früher gelesen hat, braucht für neue Texte unter Umständen eine neue Verbindung oder eine neue Unterhaltung.
- Die Service-Adresse rechnet nur. Sie kann den Service nicht ändern und bietet genau einen Service an.
- Auch ein verbundener Agent kann nicht alles. Er kann keinen Service zurückziehen oder löschen, keine einzelnen Zellen einer bestehenden Arbeitsmappe ändern und keine Service-Tokens anlegen oder widerrufen.
- Die Anmeldung gibt es für Claude, ChatGPT und Claude Code. Jeder andere Client verbindet sich mit einem Schlüssel. Ein Konto kann bis zu 25 Verbindungen haben.
- SpreadAPI kann den Assistenten nicht zum Aufruf zwingen. Eine gute Beschreibung und Beispielfragen machen ihn zuverlässig. Du kannst auch direkt sagen: "Nutze dafür den SpreadAPI-Service."
- SpreadAPI kann nicht verhindern, dass der Assistent ein Ergebnis falsch wiedergibt. Lass dir die Werte so zeigen, wie sie zurückkamen, wenn du sicher sein musst.
- SpreadAPI rechnet, was deine Formeln sagen. Ist das Modell falsch, ist die Antwort falsch. Teste den Service vor dem Veröffentlichen mit Werten, deren Ergebnis du kennst.
Mehr dazu: AI troubleshooting.
FAQ
Muss ich einen MCP-Server für Excel installieren oder selbst betreiben?
Nein. Bei SpreadAPI ist der MCP-Server eine Adresse. Dein eigener Assistent nutzt https://spreadapi.io/mcp, und jeder veröffentlichte Service hat eine eigene Adresse der Form https://spreadapi.io/api/mcp/service/{serviceId}. Du trägst die Adresse in deinem KI-Client als eigenen Konnektor ein.
Kann der Assistent meine Formeln sehen?
Nicht über die MCP-Adresse eines Service, die Discovery-Adresse oder die API: Aufrufer bekommen nur Eingaben und Ergebnisse. Ein Assistent, der mit deinem eigenen Konto verbunden ist und die Stufe Bearbeiten oder Vollzugriff hat, kann Zellen und Formeln der Services lesen, die er erreichen darf. Wähle die Stufe Nutzen, wenn er nur rechnen soll.
Welche KI-Assistenten lassen sich verbinden?
Claude und ChatGPT verbinden sich per Anmeldung, Claude Code mit einem Befehl. Jeder andere KI-Client, der MCP-Server unterstützt, verbindet sich mit einem Schlüssel. Ein Agent ohne MCP nutzt die Discovery-Adresse, die über einfaches HTTP funktioniert.
Brauche ich ein Token, um Claude zu verbinden?
Nein. Claude meldet sich über deinen Browser an, und die Verbindung selbst ist der Zugang. Services, die durch ein Token geschützt sind, lassen sich über die Verbindung ohne Token aufrufen.
Wie nutzt ein Kunde meinen geschützten Service in ChatGPT?
Gib ihm die MCP-Adresse des Service und ein Token, das du unter API → Zugriff erstellt hast. ChatGPT verlangt eine Anmeldung, der Kunde fügt das Token ein und bestätigt. Die Anmeldung hält 12 Stunden, danach fragt ChatGPT erneut. Ein SpreadAPI-Konto braucht der Kunde nicht.
Kann ein Assistent meine Arbeitsmappe durch einen Aufruf verändern oder beschädigen?
Nein. Eine Berechnung liest nur: Sie setzt die Eingabewerte für diesen einen Aufruf, liest die Ergebnisse und lässt Arbeitsmappe und Service, wie sie waren. Ändern kann einen Service nur ein Assistent, der mit deinem Konto verbunden ist und das Recht zum Bearbeiten hat.
Wie es weitergeht
- Claude Desktop + Excel: die Schritt-für-Schritt-Anleitung zum Verbinden von Claude
- MCP-Server für Excel: die Produktseite
- How AI assistants use a service
- Connect Claude und Connect ChatGPT
- The MCP address of one service
- The discovery address
- Describe a service for AI
- Tokens and access
- What a connected agent can do