@chinchillaenterprises/mcp-stripe/README.md

Multi-tenant Stripe MCP server with account management and credential persistence

# MCP Stripe Server

[![NPM Version](https://img.shields.io/npm/v/@chinchillaenterprises/mcp-stripe)](https://www.npmjs.com/package/@chinchillaenterprises/mcp-stripe)

A comprehensive Model Context Protocol (MCP) server for Stripe API integration, providing 13 powerful tools for managing products, customers, subscriptions, and more through natural language interactions with Claude.

## 🚀 Quick Start

```bash
# Install the server
claude mcp add stripe -s user \
  -e STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key \
  -- npx @chinchillaenterprises/mcp-stripe

# Start Claude and try it out
claude
# Try: "List all my products" or "Show me active subscriptions"
```

## 📋 Available Tools

### Core Discovery Tools
- **`stripe_list_products`** - List all products in your account
- **`stripe_list_prices`** - List all pricing tiers/plans  
- **`stripe_list_coupons`** - List all promo codes/coupons
- **`stripe_list_customers`** - View customers in your account
- **`stripe_list_subscriptions`** - Check active subscriptions

### Detailed GET Tools
- **`stripe_get_product`** - Get specific product details by ID
- **`stripe_get_price`** - Get specific price details by ID
- **`stripe_get_coupon`** - Get promo code details by ID
- **`stripe_get_subscription`** - Get subscription details by ID

### Coupon Management Tools
- **`stripe_create_coupon`** - Create a new coupon/promo code
- **`stripe_delete_coupon`** - Delete a coupon by ID

### Nice-to-Have Tools
- **`stripe_list_invoices`** - See billing history
- **`stripe_list_payment_methods`** - Check saved payment methods for a customer
- **`stripe_search_customers`** - Find customers by email/name

## 🔧 Installation

### Prerequisites
- A Stripe account with API access
- Claude Code installed
- Your Stripe Secret Key (starts with `sk_test_` or `sk_live_`)

### Option 1: NPX Installation (Recommended)

```bash
# Add to Claude Code with user scope (available globally)
claude mcp add stripe -s user \
  -e STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key \
  -- npx @chinchillaenterprises/mcp-stripe

# Or add to project scope (team sharing)
claude mcp add stripe -s project \
  -e STRIPE_SECRET_KEY=sk_test_your_stripe_secret_key \
  -- npx @chinchillaenterprises/mcp-stripe
```

### Option 2: Manual Configuration

Edit your `~/.claude.json` file:

```json
{
  "mcpServers": {
    "stripe": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@chinchillaenterprises/mcp-stripe"],
      "env": {
        "STRIPE_SECRET_KEY": "sk_test_your_stripe_secret_key"
      }
    }
  }
}
```

### ⚠️ Important: API Key Security

- **Test Mode**: Use `sk_test_...` keys for development
- **Live Mode**: Use `sk_live_...` keys for production (be careful!)
- **Restricted Keys**: Consider creating restricted API keys in your Stripe Dashboard for enhanced security

## 💡 Usage Examples

### Discovering Your Data

```
# List products
"Show me all my products"
"List active products only"

# Check customers
"List my customers"
"Find customers with email containing 'john'"

# Review subscriptions
"Show me all active subscriptions"
"List subscriptions for customer cus_1234567890"
```

### Getting Specific Details

```
# Product details
"Get details for product prod_1234567890"

# Subscription information
"Show me subscription details for sub_1234567890"

# Customer payment methods
"List payment methods for customer cus_1234567890"
```

### Business Intelligence

```
# Revenue analysis
"List all paid invoices from last month"
"Show me all active subscriptions and their amounts"

# Customer support
"Search for customer with email john@example.com"
"Show me all invoices for customer cus_1234567890"
```

## 🛠️ Tool Parameters

### List Tools Parameters

Most list tools accept these common parameters:

- **`limit`** (number): Number of items to return (max 100, default 10)
- **`active`** (boolean): Filter by active status (where applicable)

### Specific Parameters

#### `stripe_list_prices`
- `product` (string): Filter by product ID

#### `stripe_list_subscriptions`  
- `status` (string): Filter by status (`active`, `canceled`, `incomplete`, etc.)
- `customer` (string): Filter by customer ID

#### `stripe_list_invoices`
- `customer` (string): Filter by customer ID
- `status` (string): Filter by status (`draft`, `open`, `paid`, `uncollectible`, `void`)

#### `stripe_list_payment_methods`
- `customer` (string): **Required** - Customer ID
- `type` (string): Payment method type (`card`, `us_bank_account`, etc.)

#### `stripe_search_customers`
- `query` (string): **Required** - Search query (email, name, or phone)

## 🔍 Troubleshooting

### Common Issues

1. **"STRIPE_SECRET_KEY environment variable is required"**
   - Ensure you've set the environment variable when adding the server
   - Check that your API key is correct and starts with `sk_test_` or `sk_live_`

2. **"No such customer/product/subscription"**
   - Verify the ID is correct and exists in your Stripe account
   - Make sure you're using the right environment (test vs live)

3. **Server not connecting**
   - Check server status: `/mcp` in Claude
   - Restart Claude after adding the server
   - Use `claude --mcp-debug` for detailed logs

### Debugging

```bash
# Check server status
claude mcp list

# Test server connection
claude mcp get stripe

# Debug mode
claude --mcp-debug
```

## 🏗️ Development

### Local Development

```bash
# Clone and setup
git clone https://github.com/chinchillaenterprises/ChillMCP
cd ChillMCP/mcp-stripe

# Install dependencies
npm install

# Build
npm run build

# Test locally
claude mcp add stripe-local -s user \
  -e STRIPE_SECRET_KEY=sk_test_your_key \
  -- node $(pwd)/dist/index.js
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly with both test and live Stripe accounts
5. Submit a pull request

## 📚 Stripe API Reference

This server implements tools for the following Stripe resources:

- [Products](https://stripe.com/docs/api/products)
- [Prices](https://stripe.com/docs/api/prices)  
- [Coupons](https://stripe.com/docs/api/coupons)
- [Customers](https://stripe.com/docs/api/customers)
- [Subscriptions](https://stripe.com/docs/api/subscriptions)
- [Invoices](https://stripe.com/docs/api/invoices)
- [Payment Methods](https://stripe.com/docs/api/payment_methods)

## 🔒 Security Best Practices

- Use test API keys during development
- Create restricted API keys with minimal required permissions
- Never commit API keys to version control
- Use environment variables for API key storage
- Regularly rotate your API keys

## 📄 License

MIT License - see LICENSE file for details.

## 🤝 Support

- [Stripe Documentation](https://stripe.com/docs)
- [MCP Documentation](https://modelcontextprotocol.io/)
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)

---

**Built by Chinchilla Enterprises** - Part of the ChillMCP server collection.