# gumroad-mcp

Read-only **MCP server for your Gumroad store** — products, sales, and revenue summaries, exposed as tools your AI agent can call.

Built by a store operator, not from the API docs alone:

- **Sales are fully paginated — and say so when they aren't.** The v2 sales endpoint pages by `page_key`; naive clients read page 1 and silently under-report. This server walks every page. There is a hard page cap so a huge store can't hang a session, and if that cap is ever hit the response carries `"complete": false` plus an explicit warning that the totals are a floor. A truncated total is never returned as if it were the real number.
- **Money is integer cents + a formatted string.** Models shouldn't do float arithmetic on revenue.
- **Refunds are first-class.** `sales` and `revenue_summary` report gross *and* net-of-refunds.
- **Buyer privacy by default.** Sales rows expose the buyer's email *domain* only — enough for channel analysis, no PII handed to the model.
- **Read-only by design.** Only GET endpoints. The token comes from the environment and is never echoed or logged.
- **No false delivery alarms.** Gumroad returns an *empty* `file_info` for multi-file products, so "empty" does not mean "no file attached". This server reports that field as the raw API fact it is (`file_info_reported_by_api`) and attaches a note, instead of asserting a delivery status the endpoint cannot actually tell you.

> **Requires the 1.x MCP SDK.** `mcp` 2.0.0 removed `mcp.server.fastmcp`, so the dependency is pinned `mcp>=1.0.0,<2.0.0`. Porting to the 2.x (`mcp.server.mcpserver`) API is tracked as follow-up.

## Tools

| Tool | What it answers |
|---|---|
| `list_products()` | What am I actually selling? Name, permalink, price, published state, sales count |
| `sales(after, before, product_id)` | Every sale in a window, paginated to the end, with totals |
| `revenue_summary(after)` | One-call health check: product counts, lifetime sales per product, revenue since a date (default: this month) |

## Install

```bash
git clone https://github.com/stcmain/gumroad-mcp.git
cd gumroad-mcp
pip install .
```

Get a token: Gumroad → Settings → Advanced → Applications → create app → copy the access token.

Register with Claude Code:

```bash
claude mcp add --scope user gumroad --env GUMROAD_ACCESS_TOKEN=your_token -- gumroad-mcp
```

Or any MCP client config:

```json
{
  "mcpServers": {
    "gumroad": {
      "command": "gumroad-mcp",
      "env": { "GUMROAD_ACCESS_TOKEN": "your_token" }
    }
  }
}
```

## License

MIT © Zachary Pampu