<div align="center">

💳 stripe-mcp

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

<p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-key-features">Key Features</a> • <a href="#-architecture">Architecture</a> • <a href="#-sub-documentation-map">Sub-Docs Map</a> • <a href="#-austrian--eu-compliance">Tax & Entity Rules</a> </p>

---

</div>

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.

---

✨ 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.
• 🛡️ Financial Safety Caps: Strict hard limit (MAX_REFUND_AMOUNT_EUR = €500.00) blocking unauthorized agent refund overruns.
• 🇦🇹 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.

---

🇦🇹 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

Area	Documentation Link	Description
🖥️ Webapp Dashboard	webapp/README.md	React 18, Vite, TailwindCSS dashboard guide & setup.
🐍 Python Backend	src/stripe_mcp/README.md	Core FastMCP server, tools, and tax engine reference.
📚 Master Docs Stack	docs/README.md	Index of onboarding, configuration, tools, and troubleshooting guides.
📖 System & Help Manual	docs/HELP.md	Full Stripe system manual, GmbH & entity guide, fleet map, and KYC rules.
🚀 Onboarding Runbook	docs/ONBOARDING.md	Step-by-step account registration, single vs multi-person UBO rules & Meldezettel verification.
⚙️ Configuration	docs/CONFIGURATION.md	Environment variables & financial safety cap settings.
🛠️ Tools Reference	docs/TOOLS.md	Complete parameter schemas & return types for all tools.
📝 MCPB Prompts	assets/prompts/README.md	MCPB 3-4-100 prompts metrics and validation.
🧪 Test Suite	tests/README.md	Pytest test suite & compliance assertions.
🔧 Scripts	scripts/README.md	Maintenance & MCPB packaging scripts.

---

📄 License

Distributed under the MIT License. See LICENSE for details.