# MCP Server for Creem.io

[![npm version](https://badge.fury.io/js/mcp-server-creem.svg)](https://www.npmjs.com/package/mcp-server-creem)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub issues](https://img.shields.io/github/issues/Selenium39/mcp-server-creem)](https://github.com/Selenium39/mcp-server-creem/issues)
[![GitHub stars](https://img.shields.io/github/stars/Selenium39/mcp-server-creem)](https://github.com/Selenium39/mcp-server-creem/stargazers)

A Model Context Protocol (MCP) server for [Creem.io](https://creem.io) - the payment partner for SaaS businesses. This server provides tools to manage subscriptions, products, payments, and more through the Creem API.

## Features

- **Product Management**: Create, retrieve, and search products
- **Checkout Sessions**: Generate payment links and checkout sessions
- **Subscription Management**: Handle recurring subscriptions, upgrades, and cancellations
- **Customer Management**: Manage customers and generate portal links
- **License Keys**: Activate, validate, and deactivate software licenses
- **Discount Codes**: Create and manage discount codes
- **Transactions**: Search and retrieve payment transactions
- **Test Mode**: Full support for Creem's test environment

## Installation

```bash
npm install mcp-server-creem
```

Or install from source:

```bash
git clone https://github.com/Selenium39/mcp-server-creem.git
cd mcp-server-creem
npm install
npm run build
```

## Configuration

### Environment Variables

Set the following environment variables:

- `CREEM_API_KEY` (required): Your Creem API key
- `CREEM_TEST_MODE` (optional): Set to `true` to use test mode (default: `false`)

### Getting Your API Key

1. Go to the [Creem Dashboard](https://creem.io/dashboard/home)
2. Navigate to the "Developers" section in the top navbar
3. Click the eye icon to reveal your API key
4. Copy and save it securely

### MCP Settings Configuration

Add this to your MCP settings file (e.g., `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "creem": {
      "command": "node",
      "args": ["/path/to/mcp-server-creem/build/index.js"],
      "env": {
        "CREEM_API_KEY": "your-api-key-here",
        "CREEM_TEST_MODE": "true"
      }
    }
  }
}
```

For Claude Desktop on macOS, the config file is typically at:
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

## Available Tools

### Product Management

#### `create_product`
Create a new product (one-time or subscription).

**Parameters:**
- `name` (required): Product name
- `price` (required): Price in cents (e.g., 1000 = $10.00)
- `billing_type` (required): "one-time" or "recurring"
- `description` (optional): Product description
- `currency` (optional): Currency code (default: "EUR")
- `billing_period` (optional): For recurring products (e.g., "every-month", "every-year")
- `tax_category` (optional): Tax category (default: "saas")
- `image_url` (optional): Product image URL

**Example:**
```json
{
  "name": "Pro Plan",
  "description": "Professional subscription",
  "price": 2900,
  "currency": "USD",
  "billing_type": "recurring",
  "billing_period": "every-month"
}
```

#### `get_product`
Retrieve product details by ID.

**Parameters:**
- `product_id` (required): Product ID

#### `search_products`
List all products.

**Parameters:**
- `page_number` (optional): Page number (default: 1)
- `page_size` (optional): Items per page (default: 50, max: 100)

### Checkout Sessions

#### `create_checkout`
Create a checkout session for a product.

**Parameters:**
- `product_id` (required): Product ID
- `request_id` (optional): Custom tracking ID
- `success_url` (optional): Redirect URL after payment
- `customer_email` (optional): Pre-fill customer email
- `customer_name` (optional): Pre-fill customer name
- `discount_code` (optional): Apply discount code
- `units` (optional): Number of seats/units
- `metadata` (optional): Custom metadata object

**Example:**
```json
{
  "product_id": "prod_abc123",
  "customer_email": "user@example.com",
  "success_url": "https://myapp.com/success",
  "metadata": {
    "user_id": "12345",
    "plan": "pro"
  }
}
```

#### `get_checkout`
Retrieve checkout session details.

**Parameters:**
- `checkout_id` (required): Checkout session ID

### Customer Management

#### `get_customer`
Get customer details by email or ID.

**Parameters:**
- `email` (optional): Customer email
- `customer_id` (optional): Customer ID

#### `list_customers`
List all customers.

**Parameters:**
- `page_number` (optional): Page number (default: 1)
- `page_size` (optional): Items per page (default: 50)

#### `create_customer_portal_link`
Generate a customer portal login link.

**Parameters:**
- `customer_id` (required): Customer ID

### Subscription Management

#### `get_subscription`
Retrieve subscription details.

**Parameters:**
- `subscription_id` (required): Subscription ID

#### `cancel_subscription`
Cancel an active subscription.

**Parameters:**
- `subscription_id` (required): Subscription ID

#### `update_subscription`
Update subscription (e.g., change seats).

**Parameters:**
- `subscription_id` (required): Subscription ID
- `items` (required): Array of items with `id` and `units`

**Example:**
```json
{
  "subscription_id": "sub_xyz789",
  "items": [
    {
      "id": "sitem_abc123",
      "units": 5
    }
  ]
}
```

#### `upgrade_subscription`
Upgrade or downgrade to a different product.

**Parameters:**
- `subscription_id` (required): Subscription ID
- `product_id` (required): New product ID
- `update_behavior` (optional): "proration-charge-immediately", "proration-charge", or "proration-none"

### License Key Management

#### `activate_license`
Activate a license key for a device/instance.

**Parameters:**
- `key` (required): License key
- `instance_name` (required): Unique device identifier

#### `deactivate_license`
Deactivate a license instance.

**Parameters:**
- `key` (required): License key
- `instance_id` (required): Instance ID

#### `validate_license`
Validate a license key.

**Parameters:**
- `key` (required): License key
- `instance_id` (required): Instance ID

### Discount Codes

#### `create_discount`
Create a discount code.

**Parameters:**
- `code` (required): Discount code (e.g., "SUMMER50")
- `type` (required): "percentage" or "fixed"
- `value` (required): Discount value
- `currency` (optional): For fixed discounts
- `max_redemptions` (optional): Usage limit
- `expires_at` (optional): Expiration date (ISO 8601)

**Example:**
```json
{
  "code": "LAUNCH50",
  "type": "percentage",
  "value": 50,
  "max_redemptions": 100
}
```

#### `get_discount`
Retrieve discount details.

**Parameters:**
- `code` (required): Discount code

#### `delete_discount`
Delete a discount code.

**Parameters:**
- `discount_id` (required): Discount ID

### Transactions

#### `search_transactions`
Search and list transactions.

**Parameters:**
- `product_id` (optional): Filter by product
- `page_number` (optional): Page number (default: 1)
- `page_size` (optional): Items per page (default: 50)

## Usage Examples

### Creating a Product and Checkout

```typescript
// 1. Create a product
const product = await create_product({
  name: "Premium Plan",
  price: 4900,
  billing_type: "recurring",
  billing_period: "every-month"
});

// 2. Create checkout session
const checkout = await create_checkout({
  product_id: product.id,
  customer_email: "customer@example.com",
  success_url: "https://myapp.com/welcome"
});

// 3. Redirect customer to checkout.checkout_url
```

### Managing Subscriptions

```typescript
// Get subscription details
const subscription = await get_subscription({
  subscription_id: "sub_abc123"
});

// Update seat count
await update_subscription({
  subscription_id: "sub_abc123",
  items: [{
    id: "sitem_xyz789",
    units: 10
  }]
});

// Cancel subscription
await cancel_subscription({
  subscription_id: "sub_abc123"
});
```

### License Key Workflow

```typescript
// Activate license
const activated = await activate_license({
  key: "LICENSE-KEY-HERE",
  instance_name: "user-macbook-pro"
});

// Validate on app startup
const isValid = await validate_license({
  key: "LICENSE-KEY-HERE",
  instance_id: activated.instance[0].id
});

// Deactivate when transferring
await deactivate_license({
  key: "LICENSE-KEY-HERE",
  instance_id: activated.instance[0].id
});
```

## Test Mode

To test your integration without real payments:

1. Set `CREEM_TEST_MODE=true` in your environment
2. Use test API key from your Creem dashboard
3. Use test card: `4242 4242 4242 4242` (any CVV/expiry)

All functionality works the same in test mode, but no real charges occur.

## Error Handling

The server returns detailed error messages:

```json
{
  "content": [{
    "type": "text",
    "text": "Error: Creem API Error (401): Invalid API key"
  }],
  "isError": true
}
```

Common errors:
- **401**: Invalid API key
- **403**: Forbidden - check permissions
- **404**: Resource not found
- **400**: Invalid parameters

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run watch

# Run in development
npm run dev
```

## Resources

- [Creem Documentation](https://docs.creem.io)
- [Creem API Reference](https://docs.creem.io/api-reference/introduction)
- [Creem Dashboard](https://creem.io/dashboard)
- [MCP Protocol](https://modelcontextprotocol.io)

## Support

- Email: [support@creem.io](mailto:support@creem.io)
- Discord: [Join Community](https://discord.gg/q3GKZs92Av)
- Documentation: [docs.creem.io](https://docs.creem.io)

## License

MIT

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Security

Never commit your API keys. Always use environment variables. Report security issues to [support@creem.io](mailto:support@creem.io).

## Sponsored By

<div align="center">

### This project is proudly supported by [ChatTempMail](https://chat-tempmail.com)

[![ChatTempMail](https://chat-tempmail.com/icons/icon-192x192.png)](https://chat-tempmail.com)

**ChatTempMail** - Professional temporary email service for developers and testers.

🚀 **Looking for more MCP servers?** Check out [mcp-server-tempmail](https://github.com/Selenium39/mcp-server-tempmail) - A powerful MCP server for managing temporary email addresses!

</div>

---

<div align="center">

**Made with ❤️ for the MCP community**

[Report Bug](https://github.com/Selenium39/mcp-server-creem/issues) · [Request Feature](https://github.com/Selenium39/mcp-server-creem/issues) · [GitHub](https://github.com/Selenium39/mcp-server-creem)

</div>