Model Context Protocol (MCP) server for Stripe API integration. Provides comprehensive access to Stripe's payment processing, subscription management, and customer data.

Features

🔐 Secure Authentication - Bearer token authentication with API key
🔄 Automatic Retries - Exponential backoff with configurable retry logic
📊 Pagination Support - Cursor-based pagination with automatic iteration
🎯 Idempotency - Built-in idempotency key support for safe retries
🛡️ Type Safety - Comprehensive TypeScript types for all Stripe entities
🚀 Lazy Loading - Tool modules loaded on-demand for better performance
🔌 Dual Transport - Supports both stdio and HTTP/SSE transports
📦 Resource Handlers - Pre-built resources for common UI needs

Installation

npm install

Configuration

Create a .env file based on .env.example:

# Required
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxxxxxxxxxx

# Optional
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxxxxxxxxxx
PORT=3000
TRANSPORT_MODE=stdio  # stdio | http | dual

Environment Variables

Variable	Required	Description
`STRIPE_SECRET_KEY`	✅ Yes	Your Stripe secret API key (starts with `sk_test_` or `sk_live_`)
`STRIPE_WEBHOOK_SECRET`	❌ No	Webhook signing secret for webhook verification (starts with `whsec_`)
`PORT`	❌ No	HTTP server port for SSE transport (default: 3000)
`TRANSPORT_MODE`	❌ No	Transport mode: `stdio`, `http`, or `dual` (default: stdio)

Usage

Development Mode

npm run dev

Production Build

npm run build
npm start

Transport Modes

stdio (Default)

Used by MCP clients like Claude Desktop:

npm start
# or
TRANSPORT_MODE=stdio npm start

HTTP/SSE

For web-based integrations:

TRANSPORT_MODE=http npm start
# Server available at http://localhost:3000

Dual Transport

Run both simultaneously:

TRANSPORT_MODE=dual npm start

Tool Categories

The server provides lazy-loaded tool modules organized by functionality:

💳 Payments

charges - Create, retrieve, update, and list charges
payment-intents - Manage payment intents
payment-methods - Handle payment methods
refunds - Process and manage refunds
disputes - Handle payment disputes

👥 Customers

customers - Create and manage customers

📅 Subscriptions

subscriptions - Manage recurring subscriptions
invoices - Handle invoices and billing

🏷️ Products & Pricing

products - Manage products
prices - Handle pricing models

💰 Payouts & Balance

payouts - Manage payouts to bank accounts
balance - Check account balance and transactions

🔔 Events & Webhooks

events - Retrieve and search events
webhooks - Manage webhook endpoints

Resource URIs

Pre-built resources for UI applications:

URI	Description
`stripe://dashboard`	Account overview and key metrics
`stripe://customers`	Customer list
`stripe://payments/recent`	Recent payments and charges
`stripe://subscriptions/active`	Active subscriptions
`stripe://invoices/unpaid`	Unpaid invoices

API Client Features

Automatic Pagination

// Iterate through all customers
for await (const customer of client.paginate('customers')) {
  console.log(customer.email);
}

Idempotency Keys

// Safe retry with idempotency
const result = await client.create('charges', data, {
  idempotencyKey: client.generateIdempotencyKey()
});

Retry Logic

Automatic retry on 429 (rate limit), 409 (conflict), and 5xx errors
Exponential backoff with jitter
Respects Stripe-Should-Retry and Retry-After headers
Configurable retry count (default: 3)

Form Encoding

Stripe requires application/x-www-form-urlencoded for POST requests. The client automatically handles:

Nested object encoding with dot notation
Array parameters
Metadata fields
Null/undefined value filtering

Type Safety

All Stripe entities use branded ID types for additional type safety:

type CustomerId = string & { __brand: 'CustomerId' };
type PaymentIntentId = string & { __brand: 'PaymentIntentId' };

This prevents accidentally mixing different ID types.

Error Handling

The server provides structured error responses:

{
  "error": {
    "type": "api_error",
    "message": "The API key provided is invalid.",
    "code": "invalid_api_key"
  }
}

Common error types:

api_error - Stripe API errors
card_error - Card-related errors
rate_limit_error - Too many requests
invalid_request_error - Invalid parameters
authentication_error - Invalid API key

Health Check

When running in HTTP mode, health check available at:

curl http://localhost:3000/health

Response:

{
  "status": "healthy",
  "service": "@mcpengine/stripe",
  "version": "1.0.0",
  "timestamp": "2024-01-18T12:00:00.000Z",
  "uptime": 123.45,
  "memory": { "rss": 45678, "heapTotal": 23456, "heapUsed": 12345 },
  "node": "v22.0.0"
}

Graceful Shutdown

The server handles shutdown signals gracefully:

SIGTERM - Kubernetes/Docker shutdown
SIGINT - Ctrl+C in terminal
SIGUSR2 - Nodemon restart

Cleanup process:

Stop accepting new connections
Finish processing active requests
Close MCP server connection
Exit with code 0

Development

Project Structure

stripe/
├── src/
│   ├── clients/
│   │   └── stripe.ts        # Stripe API client
│   ├── types/
│   │   └── index.ts         # TypeScript type definitions
│   ├── tools/               # Tool modules (lazy-loaded)
│   │   ├── customers.ts
│   │   ├── charges.ts
│   │   └── ...
│   ├── server.ts            # MCP server implementation
│   └── main.ts              # Entry point
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Adding New Tools

Create a new file in src/tools/
Export an array of ToolModule objects
Register in TOOL_MODULES in src/server.ts

Testing

# Type check
npm run build

# Run in dev mode
npm run dev

Security Considerations

Never commit .env file - Contains sensitive API keys
Use test keys in development - Keys starting with sk_test_
Rotate keys regularly - Especially after security incidents
Webhook signature verification - Use STRIPE_WEBHOOK_SECRET for webhooks
Idempotency keys - Prevent duplicate charges on retries

Stripe API Version

This server uses Stripe API version 2024-01-18. The version is set in the Stripe-Version header for all requests.

License

MIT

Support

For issues and questions:

Stripe API Docs: https://stripe.com/docs/api
MCP Protocol: https://github.com/anthropics/model-context-protocol