Recharge MCP Server

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

Features

• 147 Production-Ready Tools: Complete coverage of Recharge API v2021-11
• Robust Error Handling: Automatic retries with exponential backoff for transient errors
• Flexible Authentication: Environment variables, per-request API keys, or client configuration
• Comprehensive Testing: tests covering unit, integration, and workflow scenarios
• Type-Safe Responses: Proper error messages and structured JSON responses
• Rate Limit Handling: Automatic retry on 429 responses
• Timeout Management: Configurable request timeouts with graceful handling
• Network Resilience: Automatic retry on network failures

Table of Contents

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

Quick Start

Installation

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

# Install dependencies
npm install

# Configure your API key
cp .env.example .env
echo "RECHARGE_API_KEY=sk_test_your_api_key_here" >> .env

# Validate setup
npm run check

# Run tests to verify installation
npm test

Configuration

Add to your MCP client configuration:

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

Verify Installation

# Validate all source files
npm run validate

# Run full test suite (should see 69 passing tests)
npm test

# 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 production-ready tools covering the complete Recharge API v2021-11. For detailed documentation of every tool including parameters, examples, and usage patterns, see TOOLS.md.

Tool Categories

Category	Tools	Key Features
Customer Management	13	Create, update, search customers; manage addresses, orders, subscriptions, payment methods
Subscription Management	32	Full lifecycle: create, update, pause, resume, cancel, swap products, skip charges, manage line items, delivery schedules
Charge Management	13	Process, skip, unskip, refund, delay charges; view line items, discounts, attempts
Order Management	6	List, view, update, delete, clone orders; view line items
Address Management	8	CRUD operations with validation; view related subscriptions and charges
Discount Management	12	Create, update, delete discounts; apply/remove from subscriptions, charges, orders
Advanced Operations	23	One-time products, store credits, bundle selections, async batches, retention strategies
Analytics & Reporting	2	Subscription and customer analytics with date ranges
Bulk Operations	3	Batch update subscriptions, skip/unskip multiple charges
Checkout Management	5	Create, update, process checkouts
Collections	5	Manage product collections
Metafields	5	Custom metadata for resources
Payment Methods	3	View and update payment sources
Plans	10	Subscription plans and plan management
Products	2	View product catalog
Shipping	5	Manage shipping rates
Shop	2	Shop configuration
Tax	2	Tax line management
Webhooks	5	Configure webhook endpoints
Customer Portal	2	Portal session management
Notifications	2	Email notifications

Tool Naming Convention

All tools follow the pattern: recharge_<action>_<resource>

Examples:

• recharge_get_customers - List customers
• recharge_create_subscription - Create a new subscription
• recharge_skip_charge - Skip an upcoming charge
• recharge_apply_subscription_discount - Apply a discount to a subscription

Usage Examples

Once configured, use natural language with your MCP client to interact with the Recharge API:

Natural Language Examples

• "Show me all active subscriptions for customer john@example.com"
• "Create a new monthly subscription for product variant 12345 starting February 1st"
• "Skip the next charge for subscription 67890"
• "Get all failed charges from the last week"
• "Apply discount code SAVE20 to subscription 12345"
• "Pause subscription 11111 with reason 'Customer on vacation'"
• "Update charge 22222 scheduled date to next Monday"
• "Get customer analytics for January 2024"
• "Bulk update 50 subscriptions to change quantity to 2"

Direct 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"
  }
}

Pause Subscription

{
  "tool": "recharge_pause_subscription",
  "arguments": {
    "subscription_id": "789012",
    "pause_reason": "Customer requested pause for vacation"
  }
}

Apply Discount to Subscription

{
  "tool": "recharge_apply_subscription_discount",
  "arguments": {
    "subscription_id": "789012",
    "discount_id": "555666"
  }
}

Get Subscription Analytics

{
  "tool": "recharge_get_subscription_analytics",
  "arguments": {
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }
}

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

The server includes a comprehensive test suite with 69 passing tests covering all functionality:

# Run all tests (5 test suites, 69 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

# Validate code syntax
npm run validate

Test Coverage

• Unit Tests: RechargeClient, tool handlers, all tool schemas
• Integration Tests: Complete workflows, error scenarios, MCP server integration
• Test Infrastructure: Mock fetch API, comprehensive error handling, realistic test scenarios

Test Structure

tests/
├── unit/
│   ├── recharge-client.test.js    # HTTP client tests
│   ├── tool-handlers.test.js      # Handler logic tests
│   └── all-tools.test.js          # Tool schema & execution tests
├── integration/
│   ├── mcp-server.test.js         # MCP server integration tests
│   └── all-tools.test.js          # Full workflow tests
└── setup.js                        # Test configuration

Troubleshooting

Common Issues

Server not found:

• Verify the path to index.js is correct and absolute
• Ensure Node.js is in your system PATH (Node.js >= 18 required)
• Check file permissions on the server directory
• Restart your MCP client after configuration changes

API key issues:

• Verify your API key is valid and has Admin permissions
• Check that environment variables are properly set in .env
• Ensure the API key starts with sk_live_ (production) or sk_test_ (sandbox)
• Test API connectivity:

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

Connection errors:

• Check your internet connection
• Verify Recharge API is accessible (not blocked by firewall)
• Check timeout settings if requests are timing out
• Review retry settings for transient failures

Test failures:

# Validate syntax first
npm run validate

# Check Node.js version (must be >= 18)
node --version

# Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# Run tests with verbose output
npm test -- --verbose

Import/module errors:

• Ensure you're using Node.js >= 18 with ES modules support
• Check that all import statements use .js file extensions
• Verify package.json has "type": "module"

Debug Mode

Run with detailed logging:

NODE_ENV=development npm run dev

Validation Commands

# Validate all source files
npm run validate

# Run full test suite
npm test

# Check overall setup
npm run check

Environment Variables

Variable	Default	Description
RECHARGE_API_KEY	-	Your Recharge Admin API key (required)
RECHARGE_API_URL	https://api.rechargeapps.com	API base URL
RECHARGE_API_TIMEOUT	30000	Request timeout in milliseconds
RECHARGE_API_RETRY_ATTEMPTS	3	Number of retry attempts
RECHARGE_API_RETRY_DELAY	1000	Base delay between retries (ms)

Project Structure

recharge-mcp-server/
├── index.js                        # MCP server entry point (exports RechargeServer)
├── src/
│   ├── recharge-client.js          # HTTP client with retry logic
│   ├── tool-handlers.js            # Tool execution handlers
│   └── tools/                      # 147 tool schema definitions
│       ├── index.js                # Tool exports
│       ├── customer-tools.js       # Customer management (13 tools)
│       ├── subscription-tools.js   # Subscription management (32 tools)
│       ├── charge-tools.js         # Charge management (13 tools)
│       ├── order-tools.js          # Order management (6 tools)
│       ├── address-tools.js        # Address management (8 tools)
│       ├── discount-tools.js       # Discount management (12 tools)
│       ├── advanced-tools.js       # Advanced operations (23 tools)
│       ├── analytics-tools.js      # Analytics & reporting
│       ├── bulk-tools.js           # Bulk operations
│       ├── checkout-tools.js       # Checkout management
│       ├── collection-tools.js     # Collection management
│       ├── metafield-tools.js      # Metafield operations
│       ├── payment-tools.js        # Payment methods
│       ├── plan-tools.js           # Plan management
│       ├── portal-tools.js         # Customer portal
│       ├── product-tools.js        # Product catalog
│       ├── shipping-tools.js       # Shipping rates
│       ├── shop-tools.js           # Shop configuration
│       ├── tax-tools.js            # Tax management
│       └── webhook-tools.js        # Webhook configuration
├── tests/
│   ├── unit/                       # Unit tests (3 suites)
│   │   ├── recharge-client.test.js
│   │   ├── tool-handlers.test.js
│   │   └── all-tools.test.js
│   ├── integration/                # Integration tests (2 suites)
│   │   ├── mcp-server.test.js
│   │   └── all-tools.test.js
│   └── setup.js                    # Test configuration
├── scripts/
│   └── validate.sh                 # Validation script
├── .env.example                    # Environment template
├── .env                            # Your API configuration (gitignored)
├── .gitignore
├── babel.config.cjs                # Babel configuration for Jest
├── jest.config.cjs                 # Jest test configuration
├── package.json                    # Dependencies & scripts
├── package-lock.json
├── LICENSE                         # MIT License
├── README.md                       # This file
└── TOOLS.md                        # Detailed tool documentation

Key Files

• index.js: Main MCP server implementation, exports RechargeServer class
• src/recharge-client.js: HTTP client with exponential backoff, timeout handling, and retry logic
• src/tool-handlers.js: Handler methods for all 147 tools with error handling
• src/tools/*.js: Tool schema definitions using MCP tool schema format

Development

Requirements

• Node.js >= 18.0.0 (required for ES modules and native fetch)
• npm >= 8.0.0

Setup

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Add your test API key to .env
echo "RECHARGE_API_KEY=sk_test_your_key_here" >> .env

# Run validation
npm run validate

# Run tests
npm test

Development Workflow

# Start development server with auto-reload
npm run dev

# Run tests in watch mode
npm run test:watch

# Validate code before committing
npm run check

# Run tests with coverage report
npm run test:coverage

Code Organization

• Tool Schemas: Each tool category has its own file in src/tools/
• HTTP Client: All API calls go through RechargeClient in src/recharge-client.js
• Error Handling: Centralized error handling in tool handlers
• Testing: Mock fetch for all HTTP calls, no actual API calls in tests

Adding New Tools

1. Add tool schema to appropriate file in src/tools/
2. Export the schema from src/tools/index.js
3. Add handler method to src/tool-handlers.js
4. Register handler in index.js tool mapping
5. Add tests to tests/unit/all-tools.test.js
6. Update TOOLS.md documentation

Testing Guidelines

• All tests use mock fetch, no real API calls
• Tests must be deterministic and fast
• Integration tests verify complete workflows
• Unit tests verify individual components
• All tests must pass before committing

License

MIT License - see LICENSE for details.