Stripe MCP Server

MCP-Server (Model Context Protocol), der die Stripe-API für Claude bereitstellt. Entwickelt für die Bereitstellung auf Railway im Nur-Lese-Modus.

👉 Die Bereitstellungsschritte findest du in DEPLOY-RAILWAY.md.

Was es tut

Es gibt Claude 17 Werkzeuge zur Abfrage von Stripe: Kunden, Belastungen, Zahlungen, Abonnements, Rechnungen, Katalog, Kontostand, Transaktionen, Payouts, Ereignisse und Streitfälle – plus ein generisches Werkzeug, das jeden Endpunkt erreicht, ein weiteres, das jedes Objekt anhand seiner ID auflöst, und einen aggregierten Einnahmenbericht.

Related MCP server: Stripe MCP Server

Umgebungsvariablen

Die drei Schreibsperren

Stripe bewegt echtes Geld: Ein falscher POST erstattet einem Kunden eine Zahlung, kündigt ein Abonnement oder löscht einen Datensatz für immer. Deshalb gibt es drei unabhängige Schlösser, und ein Schreibvorgang muss alle drei passieren.

1. STRIPE_READ_ONLY – der Standard hängt vom Transport ab

• stdio (lokal): Schreibvorgänge standardmäßig erlaubt. Ein einzelner vertrauenswürdiger Benutzer auf seiner eigenen Maschine.

• http (remote): Schreibvorgänge standardmäßig blockiert. Man muss STRIPE_READ_ONLY=0 absichtlich setzen, um sie zu aktivieren.

Das Vergessen der Variable bei einer öffentlichen Bereitstellung lässt es im Nur-Lese-Modus, nicht offen.

2. STRIPE_ALLOW_LIVE_WRITES – die Live-Modus-Sperre

Auch wenn du den Nur-Lese-Modus deaktivierst, lehnt ein Live-Schlüssel weiterhin Schreibvorgänge ab, bis du STRIPE_ALLOW_LIVE_WRITES=1 setzt. Testschlüssel (sk_test_, rk_test_) durchlaufen diese Sperre nicht: Das Experimentieren mit Testdaten sollte keine Zeremonie erfordern.

3. confirm=true – die Endpunkt-Sperre

Die destruktiven Endpunkte (/v1/refunds, /v1/payouts, /v1/transfers, Abonnement-Kündigungen, Löschen von Kunden, Schließen von Streitfällen) erfordern confirm=true im Aufruf, zusätzlich zu allem Vorherigen. Ein versehentlich ausgelöstes Werkzeug erreicht das nicht allein.

Jede Ablehnung sagt, welche der drei Sperren es gestoppt hat.

Authentifizierung des Endpunkts

Das MCP-Protokoll bringt keine eigene Authentifizierung mit. Im http-Modus verlangt dieser Server bei jeder Anfrage Authorization: Bearer <MCP_AUTH_TOKEN> oder das in der Route eingebettete Geheimnis (/s/<secreto>/mcp) für die Claude-Connectors. /healthz ist die einzige öffentliche Route.

Der Server weigert sich zu starten, wenn MCP_AUTH_TOKEN fehlt oder weniger als 32 Zeichen hat. Das ist beabsichtigt: Es verhindert, dass versehentlich ein offenes Gateway zu deinem Stripe-Konto veröffentlicht wird.

Lokal ausführen

pip install -r requirements.txt

# stdio (para Claude Desktop)
STRIPE_API_KEY=rk_test_xxx python stripe_mcp.py

# http (como en Railway)
STRIPE_MCP_TRANSPORT=http \
STRIPE_API_KEY=rk_test_xxx \
MCP_AUTH_TOKEN=$(python3 -c "import secrets;print(secrets.token_urlsafe(48))") \
PORT=8000 python stripe_mcp.py

Beim Start wird ausgegeben, in welchem Modus es läuft:

[stripe-mcp] streamable-http on 0.0.0.0:8000  mode=test  read_only=True  allow_live_writes=False  writes_enabled=False

Hinweise zur Stripe-API

Dinge, die der Server bereits für dich erledigt, und die man beim Lesen der Antworten wissen sollte:

• Stripe akzeptiert kein JSON im Body. Alles läuft über application/x-www-form-urlencoded mit Klammernotation: metadata[order]=6735, expand[]=customer, items[0][price]=price_1. Der Server übersetzt nur verschachtelte Dictionaries und Listen.

• Geld ist eine Ganzzahl in der kleinsten Einheit. 2500 mit usd sind $25.00. Und es gibt Währungen mit null Dezimalstellen (JPY, KRW, CLP…), bei denen die Ganzzahl der Betrag ist – eine Division durch 100 wäre dort ein Fehler. Die formatierten Ausgaben respektieren das.

• Test und Live sind getrennte Universen. Eine in Test erstellte ID gibt mit einem Live-Schlüssel 404 zurück und umgekehrt. Das ist die häufigste Ursache für ein 404 mit einer korrekten ID.

• Die Paginierung erfolgt per Cursor, nicht per Seite. Man nimmt die letzte ID und übergibt sie als starting_after. Wenn es mehr gibt, enthält die Antwort next_page_hint mit dem genauen Wert.

• Es gibt kein PATCH oder PUT. Stripe verwendet POST sowohl zum Erstellen als auch zum Aktualisieren. Nur GET, POST und DELETE.

• Die Listen filtern nicht nach status bei charges oder payment_intents. Man muss über die zurückgegebenen Datensätze filtern oder stripe_search verwenden.

• stripe_list_subscriptions lässt die gekündigten standardmäßig aus. Für Churn-Fragen muss man status='all' übergeben, sonst ist die Antwort stillschweigend falsch.

• Der Suchindex braucht bis zu einer Minute, um ein neu erstelltes Objekt zu sehen. Für neue Objekte sucht man sie per ID.

• Ereignisse werden nur 30 Tage gespeichert. Weiter zurück muss man zu den Objekten gehen.

• Es gibt keinen Aggregations-Endpunkt. Deshalb paginiert und summiert stripe_revenue_summary auf der MCP-Serverseite und meldet mit complete=false, wenn das Seitenlimit die Zählung abgeschnitten hat – diese Summen sind teilweise und dürfen nicht als endgültig gemeldet werden.

• Jeder POST wird mit einem Idempotency-Key gesendet, sodass ein erneuter Versuch nicht doppelt belastet. Stripe merkt sich diese 24 Stunden.

Sicherheit

• Geheimnisse gehören in Umgebungsvariablen, niemals in den Code. Die .gitignore blockiert .env-Dateien.

• Verwende einen Restricted Key (rk_...), nicht den Secret Key. Sie werden im Dashboard beliebig oft erstellt und erhalten Berechtigungen pro Ressource. Für diese Bereitstellung: alles auf Read, nichts auf Write. Ein sk_live_ gibt vollen Zugriff auf das Konto, einschließlich Geldbewegungen.

• Ein einzelnes gemeinsames Token bedeutet null Rückverfolgbarkeit pro Person. Alles, was jemand tut, wird als derselbe Schlüssel protokolliert.

• Es gibt kein eigenes Rate Limiting. Wer den MCP_AUTH_TOKEN hat, kann Stripe so lange anfragen, bis er auf das Stripe-Limit stößt (~100 Leseanfragen/s im Live-Modus).

• Um den Zugriff sofort zu unterbrechen: Lösche den Restricted Key unter https://dashboard.stripe.com/apikeys – der Server ist sofort nutzlos.