lemonsqueezy-mcp

A Model Context Protocol server for Lemon Squeezy — 44 audited tools over the official SDK, security-first. Works with any Lemon Squeezy account.

An independent, unofficial integration — not affiliated with or endorsed by Lemon Squeezy.

What this is

An MCP server that lets Claude (Claude Code, Cowork, Claude Desktop) — or any MCP-capable client — talk to your Lemon Squeezy account in plain language. Every tool is a thin, audited wrapper around the official @lemonsqueezy/lemonsqueezy.js SDK. The server runs locally over stdio; your API key never leaves your machine.

Features

44 MCP tools cover the full Lemon Squeezy API surface:

Category	Read	Mutating	Total
Meta	1	0	1
Stores	2	0	2
Products / Variants / Prices	6	0	6
Subscriptions	2	4	6
Customers	2	3	5
Orders	3	1	4
Discounts	3	2	5
License Keys	4	3	7
Checkouts	2	1	3
Webhooks	2	3	5
Total	27	17	44

Plus a security model built in (key never leaked, redacted audit log, store allowlist, read-only mode, test_mode signalling — see below) and two workflow skills (skills/) that chain the tools into reproducible tasks: lemonsqueezy-tier-setup and lemonsqueezy-webhook-test.

Install

Via npx (no install — recommended for MCP clients): see Connect your MCP client below; npx fetches the package on first run.

Global:

npm install -g @heysash/lemonsqueezy-mcp
lemonsqueezy-mcp   # starts a stdio server (expects LEMONSQUEEZY_API_KEY in env)

From source:

git clone https://github.com/heysash/lemonsqueezy-mcp.git
cd lemonsqueezy-mcp
npm install
npm run build

Requires Node.js ≥ 18.

Configure

Set your Lemon Squeezy API key. Get one from app.lemonsqueezy.com/settings/api.

LEMONSQUEEZY_API_KEY=<your Lemon Squeezy API key>

Optional:

Variable	Effect
LEMONSQUEEZY_ALLOWED_STORE_IDS=12345,67890	Reject destructive tool calls that target any other store. Strongly recommended when you have a test + production store.
LEMONSQUEEZY_AUDIT_LOG_FILE=./audit-logs/lemonsqueezy-mcp.jsonl	Append every destructive call to a JSONL file. Stderr logging is always on.
LEMONSQUEEZY_READ_ONLY=true	Disable all destructive tools (create/update/delete/cancel/pause/resume/refund). Useful for audit sessions.

Connect your MCP client

Add the server to your MCP configuration — e.g. ~/.claude.json, an .mcp.json in your repo, or Claude Desktop's config:

{
  "mcpServers": {
    "lemonsqueezy-mcp": {
      "command": "npx",
      "args": ["-y", "@heysash/lemonsqueezy-mcp"],
      "env": {
        "LEMONSQUEEZY_API_KEY": "your-key-here"
      }
    }
  }
}

To run a locally built copy instead of npx, use "command": "node", "args": ["/absolute/path/to/lemonsqueezy-mcp/dist/index.js"] (see examples/claude-code-mcp-config.json).

Restart the client and verify with lemonsqueezy_whoami from a chat — it reports the authenticated account and whether the key is a test or live key.

Tool catalogue

Tool	What it does	Destructive
lemonsqueezy_whoami	Verify the API key; surfaces test_mode	—
lemonsqueezy_list_stores / lemonsqueezy_get_store	Stores	—
lemonsqueezy_list_products / lemonsqueezy_get_product	Products	—
lemonsqueezy_list_variants / lemonsqueezy_get_variant	Variants (pricing tiers)	—
lemonsqueezy_list_prices / lemonsqueezy_get_price	Prices	—
lemonsqueezy_list_subscriptions / lemonsqueezy_get_subscription	Subscriptions	—
lemonsqueezy_update_subscription	Change variant, billing anchor, proration	✓
lemonsqueezy_cancel_subscription	Cancel at period end	✓
lemonsqueezy_pause_subscription / lemonsqueezy_resume_subscription	Pause / resume	✓
lemonsqueezy_list_customers / lemonsqueezy_get_customer	Customers	—
lemonsqueezy_create_customer / lemonsqueezy_update_customer / lemonsqueezy_archive_customer	CRUD	✓
lemonsqueezy_list_orders / lemonsqueezy_get_order / lemonsqueezy_list_order_items	Orders	—
lemonsqueezy_refund_order	Issue refund	✓
lemonsqueezy_list_discounts / lemonsqueezy_get_discount / lemonsqueezy_list_discount_redemptions	Discounts	—
lemonsqueezy_create_discount / lemonsqueezy_delete_discount	Create / delete discount codes	✓
lemonsqueezy_list_license_keys / lemonsqueezy_get_license_key / lemonsqueezy_list_license_key_instances / lemonsqueezy_validate_license	License keys	—
lemonsqueezy_update_license_key / lemonsqueezy_activate_license / lemonsqueezy_deactivate_license	Mutating	✓
lemonsqueezy_list_checkouts / lemonsqueezy_get_checkout	Checkouts	—
lemonsqueezy_create_checkout	Create a one-off checkout URL	✓
lemonsqueezy_list_webhooks / lemonsqueezy_get_webhook	Webhooks	—
lemonsqueezy_create_webhook / lemonsqueezy_update_webhook / lemonsqueezy_delete_webhook	Mutating	✓

API constraint: Lemon Squeezy does NOT allow creating products or variants via the REST API — they must be created in the dashboard. The lemonsqueezy-tier-setup skill wires dashboard-created products into your config rather than creating them from scratch.

Skills

Optional Claude skills (plain markdown under skills/) that turn the tools into reproducible workflows. Copy them into your skill registry (cp -r skills/lemonsqueezy-* ~/.claude/skills/):

• lemonsqueezy-tier-setup — discover a store's subscription tiers and emit .env lines + a summary table.
• lemonsqueezy-webhook-test — send signature-valid synthetic webhook payloads to your handler and check the responses. (Lemon Squeezy has no official test-webhook API — this fills the gap.)

Security model

Payment tooling handles a live API key, so security is a first-class design goal, not an afterthought:

• The API key is read only from LEMONSQUEEZY_API_KEY and never appears in tool responses, error messages or audit logs.
• Audit log entries automatically redact any field whose key matches apiKey, api_key, authorization, token, secret, password, lemonsqueezy_api_key.
• Destructive tools carry the MCP destructiveHint: true annotation so the client can ask for confirmation before mutating anything.
• Store allowlist is enforced: with LEMONSQUEEZY_ALLOWED_STORE_IDS set, any destructive tool that targets a store outside the list is rejected and audited as denied.
• LEMONSQUEEZY_READ_ONLY=true disables every destructive tool — recommended for shared MCP sessions.
• lemonsqueezy_whoami surfaces the response-level test_mode flag, so a caller can confirm a key operates on test data before any write.

Develop

npm run dev          # tsx-watch the server (stdio)
npm run test         # vitest unit + protocol-level integration
npm run coverage     # vitest run --coverage (v8), enforced ≥ 90% lines/statements
npm run lint         # eslint (flat config)
npm run smoke        # API-free end-to-end smoke test against the compiled binary
npm run typecheck    # tsc --noEmit

For a real-API check against your own Test-Mode account, scripts/live-verify.mjs drives the compiled server over stdio through a plan of tool calls. Launch it with the key injected by your secret manager — never persist or echo the key, e.g. op run --env-file=<template> -- node scripts/live-verify.mjs <plan.json> [out.json].

See CONTRIBUTING.md for the full workflow.

Works with

Any Lemon Squeezy account, and any framework or language — the server speaks the MCP protocol over stdio. It pairs naturally with SaaS apps that bind checkouts to their own users via Lemon Squeezy custom_data.

Maintainer

Built and maintained by heysash Studio (Sascha Rahn).

License

MIT © heysash Studio (Sascha Rahn) — see LICENSE and NOTICE.