# Stripe Mcp Server

> Local MCP server for Stripe with PII redaction, Zod validation, and idempotency keys

- **Type:** MCP server
- **Install:** `agentstack add mcp-udaykapur-stripe-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [udaykapur](https://agentstack.voostack.com/s/udaykapur)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [udaykapur](https://github.com/udaykapur)
- **Source:** https://github.com/udaykapur/stripe-mcp-server

## Install

```sh
agentstack add mcp-udaykapur-stripe-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Stripe MCP Server

A local [Model Context Protocol](https://modelcontextprotocol.io/) 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](https://dashboard.stripe.com/apikeys))

### Install and build

```bash
git clone 
cd stripe-mcp-server
npm install
npm run build
```

### Environment

```bash
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](https://docs.stripe.com/keys#limit-access) (`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`)

```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`)

```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

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

## Project structure

```text
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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [udaykapur](https://github.com/udaykapur)
- **Source:** [udaykapur/stripe-mcp-server](https://github.com/udaykapur/stripe-mcp-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-udaykapur-stripe-mcp-server
- Seller: https://agentstack.voostack.com/s/udaykapur
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.