# ClickBank MCP Server

Stdio [Model Context Protocol](https://modelcontextprotocol.io) server for [ClickBank REST 1.3](https://support.clickbank.com/en/articles/10535400-clickbank-apis). Cursor and other MCP hosts can query analytics, orders, products, quickstats, shipping, and tickets. Write operations (refunds, catalog edits, subscription changes) are off unless you opt in.

## Setup

1. Create an API key in ClickBank: [How to create ClickBank API keys](https://support.clickbank.com/en/articles/10535395-how-to-create-clickbank-api-keys).
2. Grant the key the roles you need (`api_order_read`, `api_products_client`, `api_order_write`, `api_subscription_modifications`, and so on).
3. Copy `.env.example` and fill in values (the server reads process env, not the file, unless your host injects it).

```bash
npm install
npm run build
```

Required environment:

| Variable | Purpose |
| --- | --- |
| `CLICKBANK_API_KEY` | Clerk key, including the `API-` prefix |
| `CLICKBANK_ACCOUNT` | Default nickname (5–10 lowercase alphanumeric). Required for analytics; default for quickstats |
| `CLICKBANK_ENABLE_WRITES` | Set to `true` to register refund, product, shipping-notice, and subscription tools |
| `CLICKBANK_DEV_KEY` | Optional legacy developer key; Authorization becomes `DEV-…:API-…` |
| `CLICKBANK_BASE_URL` | Override API root (default `https://api.clickbank.com/rest/1.3`) |

ClickBank no longer requires a developer key. Do not log or commit the Authorization header.

## Cursor

Build first, then point Cursor at `dist/index.js`:

```json
{
  "mcpServers": {
    "clickbank": {
      "command": "node",
      "args": ["/absolute/path/to/clickbank-mcp/dist/index.js"],
      "env": {
        "CLICKBANK_API_KEY": "API-your-key-here",
        "CLICKBANK_ACCOUNT": "yournick",
        "CLICKBANK_ENABLE_WRITES": "false"
      }
    }
  }
}
```

Keep `CLICKBANK_ENABLE_WRITES` false unless you want the model to be able to refund, delete products, or change subscriptions.

## Tools

Read tools are always registered:

- **Analytics:** `get_analytics`, `get_subscription_analytics`
- **Orders:** `list_orders`, `count_orders`, `get_order`, `get_order_upsells`, `check_order_active`
- **Products:** `list_products`, `get_product`
- **Quickstats:** `list_quickstats`, `summarize_quickstats`, `list_clickbank_accounts`
- **Shipping:** `list_shippable_orders`, `count_shippable_orders`, `get_ship_notices`
- **Tickets:** `list_tickets`, `count_tickets`, `get_ticket`, `get_refund_amounts`

Write tools (only when `CLICKBANK_ENABLE_WRITES=true`):

- `modify_subscription` — product swap, address, rebill date, extend, pause, reinstate
- `save_product`, `delete_product`
- `create_ship_notice`
- `create_ticket`, `update_ticket`, `confirm_physical_return`

List endpoints return 100 rows per page. Pass `page` and optional `maxPages` (max 10). HTTP 206 means more pages remain. The client spaces requests (~8/s) to stay under ClickBank’s 10 requests/second quota.

## Development

```bash
npm test
npm run dev
```

`npm run dev` still needs `CLICKBANK_API_KEY` in the environment. Tests mock `fetch` and do not call ClickBank.