stripe-mcp-server

Stripe MCP Server

A local Model Context Protocol server for Stripe payment operations. 52 tools across 8 domains, with built-in PII redaction and input validation.

Built for AI-assisted development workflows where Stripe API access needs to be both comprehensive and safe by default.

Why this exists

Stripe's official remote MCP server (mcp.stripe.com) uses OAuth and includes doc search, but exposes a smaller toolset. This server runs locally, covers more of the Stripe API surface, and sanitises every response before it reaches the model context, so sensitive data never leaks into conversation history or logs.

| | This server | Stripe official | | ---------------- | ------------------------ | ---------------- | | Transport | stdio (local) | HTTP (remote) | | Auth | STRIPE_SECRET_KEY env | OAuth | | Tools | 52 | Smaller subset | | PII redaction | Built-in | Stripe-managed | | Doc search | No | Yes | | Idempotency keys | All mutating tools | Varies | | Input validation | Strict schemas (Zod) | Varies |

The two servers complement each other. Run both if you want operational tools plus doc search.

Tools (52)

Customers (6)

create_customer, retrieve_customer, update_customer, delete_customer, list_customers, search_customers

Payments (11)

create_payment_intent, retrieve_payment_intent, confirm_payment_intent, capture_payment_intent, cancel_payment_intent, list_payment_intents, list_payment_methods, attach_payment_method, detach_payment_method, retrieve_charge, list_charges

Subscriptions (9)

create_subscription, retrieve_subscription, update_subscription, cancel_subscription, list_subscriptions, create_product, list_products, create_price, list_prices

Invoices (8)

create_invoice, retrieve_invoice, finalize_invoice, pay_invoice, void_invoice, list_invoices, retrieve_upcoming_invoice, create_invoice_item

Checkout (5)

create_checkout_session, retrieve_checkout_session, list_checkout_sessions, create_coupon, list_coupons

Refunds (3)

create_refund, retrieve_refund, list_refunds

Balance (5)

retrieve_balance, list_balance_transactions, list_payouts, list_disputes, retrieve_dispute

Webhooks (5)

create_webhook_endpoint, delete_webhook_endpoint, list_webhook_endpoints, list_events, retrieve_event

Resources (4)

Exposed as MCP resources (read-only, sanitised):

• stripe://account - current account details
• stripe://balance - balance by currency
• stripe://webhook-endpoints - registered webhook endpoints
• stripe://products - active product catalogue with default prices

Prompts (4)

Pre-built prompt templates for common integration tasks:

• review_stripe_integration - security, error handling, and best-practice audit
• setup_webhooks - end-to-end webhook implementation guide per framework
• design_pricing - pricing model design with Stripe Products and Prices
• troubleshoot_payment - diagnose failed payments, declines, and disputes

Security posture

Every Stripe API response is sanitised before reaching MCP output:

• Secrets redacted: webhook signing secrets, PaymentIntent client_secret values, including inside expanded nested objects
• PII masked: email addresses (shows first 2 chars + domain), phone numbers (shows last 4 digits), billing/shipping addresses fully redacted
• URLs redacted: hosted invoice URLs and invoice PDF links (bearer-style access tokens)
• Metadata redacted: values stripped, keys preserved for operator context
• Unknown objects: unrecognised Stripe object types reduced to a minimal envelope (id, object, status, redacted: true) instead of passed through raw
• Input validation: Stripe IDs, currency codes, webhook event names, API versions, checkout payment method types, and balance transaction types validated against Zod schemas. Enum validators are derived from the installed Stripe SDK's type declarations at startup; if those files change shape in a future SDK version, validators degrade to allow-all with a stderr warning rather than crashing
• Idempotency: all mutating tools accept optional idempotency_key (except deletions, which Stripe treats as inherently idempotent)
• Pinned API version: 2026-05-27.dahlia, set in src/stripe-client.ts
• Bounded runtime: network retries capped at 0-5, timeout capped at 1-120 seconds

Setup

Prerequisites

• Node.js 18+ for runtime. Node ^20.19.0 or >=22.12.0 for running tests (Vite/Vitest dev dependency requirement)
• A Stripe account with API keys (dashboard.stripe.com/apikeys)

Install and build

git clone <repo-url>
cd stripe-mcp-server
npm install
npm run build

Environment

cp .env.example .env
# Edit .env with your Stripe secret key

| Variable | Required | Default | Description | | ---------------------------- | -------- | ------- | ------------------------------------------------------------------------------------------ | | STRIPE_SECRET_KEY | Yes | - | Secret key (sk_test_…, sk_live_…) or restricted key (rk_test_…, rk_live_…) | | STRIPE_MAX_NETWORK_RETRIES | No | 2 | Max retries on transient failures (0-5) | | STRIPE_TIMEOUT_MS | No | 30000 | Request timeout in milliseconds (1000-120000) |

Using restricted keys

For tighter security, use restricted keys (rk_*) instead of full secret keys. Minimum permissions per tool group:

| Tool group | Required permissions | | ------------- | ---------------------------------------------------------------- | | Customers | Customers: Read/Write | | Payments | PaymentIntents, PaymentMethods, Charges: Read/Write | | Subscriptions | Subscriptions, Products, Prices: Read/Write | | Invoices | Invoices: Read/Write | | Checkout | Checkout Sessions: Read/Write; Coupons: Read/Write | | Refunds | Refunds: Read/Write (also needs Charges or PaymentIntents: Read) | | Balance | Balance: Read; Payouts: Read; Disputes: Read | | Webhooks | Webhook Endpoints: Read/Write; Events: Read |

Grant only the groups you need. Read-only tools (list/retrieve) need only Read permission on their resource.

Wire into your MCP client

Claude Code (.mcp.json)

{
  "mcpServers": {
    "stripe": {
      "command": "node",
      "args": ["/absolute/path/to/stripe-mcp-server/dist/index.js"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_test_..."
      }
    }
  }
}

VS Code (.vscode/mcp.json)

{
  "servers": {
    "stripe": {
      "command": "node",
      "args": ["/absolute/path/to/stripe-mcp-server/dist/index.js"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_test_..."
      }
    }
  }
}

Other MCP clients

Any client that supports stdio transport can run this server. Point it at dist/index.js with STRIPE_SECRET_KEY in the environment.

Verification

npm test        # 42 tests (sanitisation, config validation, schema checks)
npm run build   # TypeScript compilation to dist/

Project structure

src/
  index.ts                   # Server entry point, tool/resource/prompt registration
  stripe-client.ts           # Stripe SDK singleton with pinned version and bounded config
  tools/
    balance.ts               # Balance and payout tools
    checkout.ts              # Checkout Session and coupon tools
    customers.ts             # Customer CRUD and search
    invoices.ts              # Invoice lifecycle tools
    payments.ts              # PaymentIntent and PaymentMethod tools
    refunds.ts               # Refund tools
    subscriptions.ts         # Subscription, Product, and Price tools
    webhooks.ts              # Webhook endpoint and event tools
  resources/index.ts         # MCP resources (account, balance, webhooks, products)
  prompts/index.ts           # MCP prompt templates
  utils/stripe-toolkit.ts    # Sanitisation, validation schemas, error formatting
tests/
  stripe-toolkit.test.ts     # Sanitisation and masking tests
  stripe-config-and-schemas.test.ts  # Config validation and schema tests

Design decisions

Sanitise by default, not by opt-in. Every Stripe object type has an explicit sanitisation path. Unknown object types are reduced rather than passed through. This means new Stripe object types added in future API versions are safe by default (they show id, status, and redacted: true until an explicit handler is added).

Validate from Stripe's own type definitions. Checkout payment method types, webhook event names, and API versions are loaded at startup from the installed Stripe SDK's TypeScript declaration files. When you upgrade the Stripe SDK, the validators update automatically. If the SDK restructures its type files in a future major version, validators degrade to allow-all with a stderr warning rather than crashing. The wildcard * webhook event is always rejected regardless of validator state.

No stored state. The server holds no data between requests beyond the Stripe SDK client singleton. All state lives in Stripe's API.

Licence

MIT