# 💳 MCP Stripe Finance

A **production-grade MCP server** for Stripe financial operations. Gives AI assistants (Claude, Cursor, VS Code, Claude Code, any MCP client) direct access to Stripe APIs — payments, customers, subscriptions, invoices, products, prices, refunds, and balance checks.

## Why This Exists

The MCP ecosystem has **325+ finance/commerce servers** but no high-quality, comprehensive Stripe MCP server existed before this one. The existing `mcp-stripe` (Python) has only 44 stars and limited functionality. This is a **TypeScript-native** implementation with **17 tools** covering the full Stripe lifecycle.

### Compared to Alternatives

| Feature | mcp-stripe-finance 🆕 | Existing mcp-stripe (Python) |
|---|---|---|
| Language | TypeScript (JS ecosystem native) | Python |
| Tools | 17 (full Stripe lifecycle) | 6 (basic CRUD) |
| npm downloads | Brand new | 0 (PyPI, not npm) |
| Customers | Create, retrieve, list | Create, retrieve, update |
| Payments | Create, list | Create, list |
| Refunds | Full + partial | Basic |
| Subscriptions | Create, list | ❌ |
| Invoices | Create, finalize, list | ❌ |
| Products | Create, list | ❌ |
| Prices | Create, list (one-time + recurring) | ❌ |
| Balance | Retrieve | ❌ |
| Charges | Retrieve, search | ❌ |
| Quality | Zod schema validation + 14 tests | No tests |

## Prerequisites

- **Node.js 18+**
- A **Stripe API key** (get one at https://dashboard.stripe.com/apikeys)
  - Use `sk_test_...` for development/testing
  - Use `sk_live_...` for production

## Quick Start

### 1. Install & Run

```bash
# Clone and install
git clone <your-repo-url>
cd mcp-stripe-finance
npm install
npm run build

# Set your Stripe key
export STRIPE_API_KEY=sk_test_your_key_here

# Start the server (stdio mode — integrates with MCP clients)
node dist/index.js
```

### 2. Install from npm (once published)

```bash
npm install -g mcp-stripe-finance
# or use directly with npx
npx mcp-stripe-finance
```

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "stripe-finance": {
      "command": "node",
      "args": ["/path/to/mcp-stripe-finance/dist/index.js"],
      "env": {
        "STRIPE_API_KEY": "sk_test_your_key_here"
      }
    }
  }
}
```

### Cursor

In Cursor settings → MCP Servers → Add:

- **Name:** Stripe Finance
- **Type:** command
- **Command:** `node /path/to/mcp-stripe-finance/dist/index.js`
- **Environment Variables:** `STRIPE_API_KEY=sk_test_your_key_here`

### VS Code (via Continue.dev or similar)

```json
{
  "mcpServers": {
    "stripe-finance": {
      "command": "node",
      "args": ["/path/to/mcp-stripe-finance/dist/index.js"],
      "env": {
        "STRIPE_API_KEY": "sk_test_your_key_here"
      }
    }
  }
}
```

### Smithery.ai (Remote Hosting)

[![Smithery Badge](https://smithery.ai/badge/mcp-stripe-finance)](https://smithery.ai/server/mcp-stripe-finance)

Configure Smithery to run the Docker image or point at your hosted instance with `STRIPE_API_KEY` environment.

## Available Tools

### 💰 Payments
| Tool | Description | Required Params |
|---|---|---|
| `stripe_create_payment_intent` | Create a payment (amount in cents) | `amount` |
| `stripe_list_payments` | List recent payment intents | — |
| `stripe_create_refund` | Issue a full or partial refund | `payment_intent` |
| `stripe_retrieve_charge` | Get charge details | `charge_id` |
| `stripe_search_charges` | Search charges with query syntax | `query` |

### 👥 Customers
| Tool | Description | Required Params |
|---|---|---|
| `stripe_create_customer` | Create a new customer | — |
| `stripe_retrieve_customer` | Get customer details | `customer_id` |
| `stripe_list_customers` | List/search customers | — |

### 💳 Subscriptions
| Tool | Description | Required Params |
|---|---|---|
| `stripe_create_subscription` | Create a subscription | `customer_id`, `items` |
| `stripe_list_subscriptions` | List subscriptions | — |

### 📄 Invoices
| Tool | Description | Required Params |
|---|---|---|
| `stripe_create_invoice` | Create a draft invoice | `customer_id` |
| `stripe_finalize_invoice` | Finalize a draft invoice | `invoice_id` |
| `stripe_list_invoices` | List invoices | — |

### 📦 Products & Pricing
| Tool | Description | Required Params |
|---|---|---|
| `stripe_create_product` | Create a product | `name` |
| `stripe_list_products` | List products | — |
| `stripe_create_price` | Create a price (one-time or recurring) | `product`, `unit_amount` |
| `stripe_list_prices` | List prices | — |

### 📊 Account
| Tool | Description | Required Params |
|---|---|---|
| `stripe_retrieve_balance` | Get account balance (available/pending) | — |

## Example Queries (What AI Can Do)

> "Create a new customer named Jane Doe with email jane@example.com"
> → `stripe_create_customer({name: "Jane Doe", email: "jane@example.com"})`

> "Charge Jane $25 for a monthly subscription"
> → `stripe_create_customer`, then `stripe_create_product`, `stripe_create_price` with recurring, `stripe_create_subscription`

> "What's my current Stripe balance?"
> → `stripe_retrieve_balance()`

> "Refund the last payment from customer cus_xyz"
> → `stripe_list_payments`, then `stripe_create_refund`

> "Create a $49.99 monthly subscription for customer cus_abc with a 14-day trial"
> → `stripe_create_subscription({customer_id: "cus_abc", items: [{price: "price_xyz"}], trial_period_days: 14})`

## Development

```bash
# Watch mode
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Inspect with MCP Inspector
npm run inspect

# Build
npm run build
```

### Testing with the MCP Inspector

```bash
# Terminal 1: Set your key and start the server
export STRIPE_API_KEY=sk_test_...
npm run inspect
```

The MCP Inspector provides a browser UI to test each tool interactively.

## Security

- **Never commit your Stripe API key.** Use environment variables or `.env` files.
- Test with `sk_test_` keys in development.
- The server provides **read-only balance** information and **write access** to your Stripe account. Be careful which AI clients have access.
- All tools require the `STRIPE_API_KEY` environment variable to be set at startup.

## License

MIT