291 lines
6.9 KiB
Markdown
291 lines
6.9 KiB
Markdown
# Stripe MCP Server
|
|
|
|
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
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create a `.env` file based on `.env.example`:
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
### Production Build
|
|
|
|
```bash
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
### Transport Modes
|
|
|
|
#### stdio (Default)
|
|
Used by MCP clients like Claude Desktop:
|
|
|
|
```bash
|
|
npm start
|
|
# or
|
|
TRANSPORT_MODE=stdio npm start
|
|
```
|
|
|
|
#### HTTP/SSE
|
|
For web-based integrations:
|
|
|
|
```bash
|
|
TRANSPORT_MODE=http npm start
|
|
# Server available at http://localhost:3000
|
|
```
|
|
|
|
#### Dual Transport
|
|
Run both simultaneously:
|
|
|
|
```bash
|
|
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
|
|
|
|
```typescript
|
|
// Iterate through all customers
|
|
for await (const customer of client.paginate('customers')) {
|
|
console.log(customer.email);
|
|
}
|
|
```
|
|
|
|
### Idempotency Keys
|
|
|
|
```typescript
|
|
// 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:
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```bash
|
|
curl http://localhost:3000/health
|
|
```
|
|
|
|
Response:
|
|
```json
|
|
{
|
|
"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:
|
|
1. Stop accepting new connections
|
|
2. Finish processing active requests
|
|
3. Close MCP server connection
|
|
4. 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
|
|
|
|
1. Create a new file in `src/tools/`
|
|
2. Export an array of `ToolModule` objects
|
|
3. Register in `TOOL_MODULES` in `src/server.ts`
|
|
|
|
### Testing
|
|
|
|
```bash
|
|
# 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
|