JJJ-Mo3/Recharge-API-MCP

Recharge MCP Server

A comprehensive Model Context Protocol (MCP) server for the Recharge API v2021-11. This server provides 147 tools for managing subscriptions, customers, orders, charges, and all other Recharge operations with robust error handling, retry logic, and flexible authentication.

Compatible with Claude Desktop, Cursor, VSCode with GitHub Copilot, and any MCP-compatible client.

Table of Contents

• Quick Start
• MCP Client Configuration
• API Key Configuration
• Available Tools
• Usage Examples
• Testing
• Troubleshooting
• License

Quick Start

# Clone the repository
git clone <repository-url>
cd recharge-mcp-server

# Install dependencies
npm install

# Copy environment template and add your API key
cp .env.example .env
# Edit .env with your Recharge API key

# Validate setup
npm run check

# Start the server
npm start

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "recharge": {
      "command": "node",
      "args": ["/path/to/recharge-mcp-server/index.js"]
    }
  }
}

Cursor IDE

Configure in Cursor settings (Cmd/Ctrl + ,) under "Extensions" > "MCP Servers":

{
  "name": "recharge",
  "command": "node",
  "args": ["/path/to/recharge-mcp-server/index.js"]
}

VSCode with GitHub Copilot

Add to VSCode settings.json:

{
  "mcp.servers": {
    "recharge": {
      "command": "node",
      "args": ["/path/to/recharge-mcp-server/index.js"]
    }
  }
}

Other MCP Clients

• Server Command: node /path/to/recharge-mcp-server/index.js
• Protocol: stdio (standard input/output)
• Environment Variables: Configure via .env file in project directory

API Key Configuration

Getting Your API Key

1. Log into your Recharge merchant portal
2. Navigate to: Apps > Custom integrations > Private App
3. Create or select a Private App to generate an Admin API key
4. Copy the API Access Token (starts with sk_live_ for production or sk_test_ for sandbox)

Configuration Methods

Method 1: Environment File (Recommended)

Create a .env file in the project root:

RECHARGE_API_KEY=sk_live_your_admin_api_key_here

# Optional configuration
RECHARGE_API_URL=https://api.rechargeapps.com
RECHARGE_API_TIMEOUT=30000
RECHARGE_API_RETRY_ATTEMPTS=3
RECHARGE_API_RETRY_DELAY=1000

Method 2: Client Environment Variables

{
  "mcpServers": {
    "recharge": {
      "command": "node",
      "args": ["/path/to/recharge-mcp-server/index.js"],
      "env": {
        "RECHARGE_API_KEY": "sk_live_your_admin_api_key_here"
      }
    }
  }
}

Method 3: Per-Request API Keys

For multi-tenant setups, provide the API key with each request:

{
  "tool": "recharge_get_customers",
  "arguments": {
    "api_key": "sk_live_your_admin_api_key_here",
    "limit": 10
  }
}

Available Tools

The server provides 147 tools covering the complete Recharge API. For detailed documentation of every tool including parameters and usage, see .

Usage Examples

Once configured, use natural language with your MCP client:

• "Show me all active subscriptions for customer john@example.com"
• "Create a new monthly subscription for product variant 12345"
• "Skip the next charge for subscription 67890"
• "Get all failed charges from the last week"
• "Apply discount code SAVE20 to subscription 12345"

Tool Examples

Get Customers

{
  "tool": "recharge_get_customers",
  "arguments": {
    "limit": 10,
    "email": "customer@example.com"
  }
}

Create Subscription

{
  "tool": "recharge_create_subscription",
  "arguments": {
    "address_id": "789012",
    "next_charge_scheduled_at": "2024-02-01T00:00:00Z",
    "order_interval_frequency": "1",
    "order_interval_unit": "month",
    "quantity": 2,
    "shopify_variant_id": "345678"
  }
}

Skip Charge

{
  "tool": "recharge_skip_charge",
  "arguments": {
    "charge_id": "333444"
  }
}

Response Format

Success Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"customer\": {\"id\": 123456, \"email\": \"customer@example.com\"}}"
    }
  ]
}

Error Response:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Recharge API error 404: Customer not found"
    }
  ],
  "isError": true
}

Testing

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests only
npm run test:integration

# Run with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

Test Structure

tests/
├── unit/
│   ├── recharge-client.test.js
│   ├── tool-handlers.test.js
│   └── all-tools.test.js
├── integration/
│   ├── mcp-server.test.js
│   └── all-tools.test.js
└── setup.js

Troubleshooting

Common Issues

Server not found:

• Verify the path to index.js is correct and absolute
• Ensure Node.js is in your system PATH
• Check file permissions on the server directory

API key issues:

• Verify your API key is valid and has Admin permissions
• Check that environment variables are properly set
• Test API connectivity:

  curl -H "X-Recharge-Access-Token: YOUR_KEY" https://api.rechargeapps.com/shop
  

Test failures:

# Validate syntax first
npm run validate

# If ES module issues, ensure Node.js >= 18
node --version

Debug Mode

Run with detailed logging:

NODE_ENV=development npm run dev

Environment Variables

Project Structure

recharge-mcp-server/
├── index.js                 # MCP server entry point
├── src/
│   ├── recharge-client.js   # HTTP client for Recharge API
│   ├── tool-handlers.js     # Tool execution handlers
│   └── tools/               # Tool schema definitions
│       ├── index.js
│       ├── customer-tools.js
│       ├── subscription-tools.js
│       ├── charge-tools.js
│       └── ...
├── tests/
│   ├── unit/
│   └── integration/
├── .env.example
├── package.json
└── README.md

License

MIT License - see for details.