💳 stripe-mcp

Stripe Gateway, SaaS Billing Ops & Austrian/EU Tax Compliance Engine

stripe-mcp is a FastMCP 3.4+ server and SOTA React webapp dashboard designed to connect autonomous AI agents (Claude Desktop, Antigravity IDE, OpenManus) and human operators with Stripe payment processing, customer support operations, subscription management, and Austrian/EU regional tax compliance (VAT 20%/10%/13%, EU ATU Reverse Charge, and BAO § 132 fiscal record retention).

⚡ Quick Start

# Navigate to repository
cd D:\Dev\repos\stripe-mcp

# Install dependencies via uv
uv sync

# Launch Backend (Port 11165) & React Webapp (Port 11166)
.\start.ps1

Once launched, open http://127.0.0.1:11166 to interact with the webapp dashboard.

Related MCP server: Stripe MCP Server

✨ Key Features

• 💳 Customer & Charge Operations: Create customers, update metadata, fetch charges, and track disputes.

• 🔁 Subscription Management: Track active subscribers, pause, resume, cancel, and monitor MRR & churn KPIs.

• 🛍️ 3DS2 Checkout Generator: Generate Stripe Payment Links & Checkout Sessions supporting Cards, EPS Online Banking, and SEPA Direct Debit.

• 🛡️ Read-Only by Default: STRIPE_READ_ONLY=true ships as the default — refunds, subscription cancels, customer creation, and all checkout/invoice creation are blocked until a human explicitly opts in. See Safety & Gating.

• 💶 Financial Safety Caps: Hard limits (MAX_REFUND_AMOUNT_EUR = €500.00, MAX_CHECKOUT_AMOUNT_EUR = €5000.00) enforced in code, independent of the read-only switch.

• 🇦🇹 Austrian & EU Tax Compliance:

  • Automatic 20% Standard VAT, 10% / 13% Reduced Rates (UStG 1994).

  • VIES/EU VAT ID syntax validation for 0% Reverse Charge (ATU\d{8}).

  • BAO § 132 7-year fiscal invoice archive lock metadata.

• 🖥️ SOTA React Webapp Dashboard (Port 11166): Catch-them-all UI with Dashboard, Customer Directory, Subscription Manager, Refund Studio, Invoice Studio, Webhook Inbox, Tools Workbench, Skills, LLM Chat, Settings, Help, and Audit Logs.

• ⚡ Mock-until-Onboarded: Works out of the box with synthetic Austrian data until your Stripe Restricted API Key (rk_test_...) is connected.

🛡️ Safety & Gating

This server sits behind an LLM. An agent that reads untrusted content (a scraped page, an inbound email, a forwarded message) can be manipulated into calling a tool it was never meant to call — so every path capable of moving money or creating a real Stripe object fails closed by default. Full threat model and rationale: docs/SAFETY.md.

Flip STRIPE_READ_ONLY=false only when you deliberately want the agent able to write. None of the controls above add friction to mock-mode demos — they apply only to real Stripe calls. Full detail on exactly what each setting gates: docs/CONFIGURATION.md.

⚖️ vs. the official Stripe MCP

Stripe ships its own hosted server at mcp.stripe.com. It's a different trade-off, not simply better or worse — see docs/HELP.md for the full comparison (verified against Stripe's docs, 2026-09-02). Short version:

• Official: OAuth, maintained by Stripe, but its entire write surface is one generic stripe_api_write tool that can call any Stripe write endpoint — no documented amount cap. Stripe's own docs recommend enabling "human confirmation of tools" in your MCP client as the prompt-injection mitigation.

• This repo: four narrow, capped, fail-closed-by-default tools, plus Austrian/EU tax logic (VAT, BAO §132, Reverse Charge) the official server doesn't have — at the cost of being a much smaller, less battle-tested project.

Use the official server for broad live-account access with tool confirmation switched on. Use this one where a narrow, capped write surface and built-in AT/EU tax compliance matter more than breadth.

🇦🇹 Austrian & EU Legal Entity & Onboarding Rules

1. Do You Need a GmbH? (No!)

Stripe supports a wide range of legal entity types in Austria:

• Einzelunternehmen (Individual / Sole Proprietorship): Freelancers (Freiberufler), solo developers, or unregistered sole traders. Requires only 1 person for identity & address verification.

• Eingetragenes Einzelunternehmen (e.U.): Sole trader registered in Commercial Register (Firmenbuch).

• GmbH / FlexCo / AG: Incorporated companies. Requires Firmenbuchauszug and verification of all UBOs holding >25% shares.

• OG / KG / Verein: Partnerships or registered non-profit associations (Verein with ZVR number).

2. Single vs. Multi-Person Verification Rules

• Einzelunternehmen: 1 person needed (yourself). Passport/ID + Meldezettel / bank statement (< 3-6 months).

• GmbH / Corporate: Under EU 5th AML directives, Stripe requires identifying and verifying the Account Representative AND all Ultimate Beneficial Owners (UBOs) holding >25% of company shares or serving as co-directors (Geschäftsführer). For standard corporate entities (e.g. GmbH with 2 co-founders), both individuals must submit identity & address verification.

3. Proof of Address (Meldezettel / Meldebestätigung Rules)

• Must be fresh (dated within 3 to 6 months). Photo ID (passport) and proof of address (Meldezettel) must be separate documents. Full-color scans showing all 4 corners required.

🏗️ Architecture

+-----------------------------------------------------------------------+
|                             AI AGENT HOST                             |
|          (Claude Desktop / Antigravity IDE / OpenManus / Cursor)      |
+-----------------------------------------------------------------------+
                                   |
                         (FastMCP stdio / HTTP /mcp)
                                   v
+-----------------------------------------------------------------------+
|                    stripe-mcp FastMCP 3.4+ SERVER                     |
|                           (Port 11165 REST/MCP)                       |
|                                                                       |
|  +------------------------+  +-------------------------------------+  |
|  |  austria_tax.py Engine |  |  Portmanteau Tools                  |  |
|  |  - 20%/10%/13% VAT       |  |  - manage_stripe_customers          |  |
|  |  - ATU Syntax Checker  |  |  - manage_stripe_subscriptions      |  |
|  |  - Reverse Charge      |  |  - manage_stripe_payments         |  |
|  |  - BAO § 132 Metadata  |  |  - manage_stripe_checkout         |  |
|  +------------------------+  +-------------------------------------+  |
+-----------------------------------------------------------------------+
            |                                           |
    (Stripe REST API)                           (SSE & REST /api)
            v                                           v
+-----------------------+               +-------------------------------+
|  Stripe Cloud Platform|               | React + Vite Webapp Dashboard |
|  - API Gateway        |               |          (Port 11166)         |
|  - Webhooks Ingest    |               | - Hero & KPIs (MRR/VAT)       |
|  - EPS / SEPA / PSD2  |               | - Mock-until-onboarded        |
+-----------------------+               | - Catch-them-all Pages        |
                                        +-------------------------------+

🗺️ Sub-Documentation Map

📄 License

Distributed under the MIT License. See LICENSE for details.