@yawlabs/lemonsqueezy-mcp

One click adds this to your local Yaw MCP config so it's available in every Yaw Terminal session. Or install manually below.

MCP server for the LemonSqueezy API. Manage your store, products, customers, subscriptions, discounts, license keys, and more from any MCP-compatible AI assistant.

Quick start

npx -y @yawlabs/lemonsqueezy-mcp@latest

Requires Node.js 22 or later (engines.node is >=22).

Or one-click install via Smithery:

npx -y @smithery/cli install @yawlabs/lemonsqueezy-mcp --client claude

Smithery prompts for your env vars (API key, optional guardrails) and writes the config into your client for you.

What it looks like

Once configured, you can ask your AI assistant store-management questions in plain English and it routes them through the MCP tools:

You:  How much did we make from the "Pro Annual" plan last month?
Claude: [calls ls_list_subscriptions, ls_get_variant, ls_list_subscription_invoices]
        Pro Annual brought in $14,280 across 84 active subscriptions in April.
        Three of those were upgrades from monthly; none churned.

You:  Refund order #LS-1234 in full.
Claude: [calls ls_get_order to fetch the total, then ls_refund_order with amount = total]
        Refunded $99.00 against order LS-1234. The customer's card will see the
        credit in 5-10 business days.

You:  Disable license key abc-123 for the customer who reported abuse.
Claude: [calls ls_list_license_keys to find the ID, then ls_update_license_key with disabled: true]
        License key disabled. Their existing activations will fail validation
        on the next check.

Guardrails (refund cap, rate limit, store allowlist) catch the obvious mistakes before they reach LemonSqueezy. See Configuration for the env vars that turn them on.

Setup

Set your LemonSqueezy API key as an environment variable:

export LEMONSQUEEZY_API_KEY="your-api-key"

Get your API key from your LemonSqueezy dashboard.

Docker

A multi-stage Dockerfile is included at the repo root. The runtime image is a single bundled file on node:22-alpine running as the non-root node user, with no port exposed (stdio transport).

docker build -t yawlabs/lemonsqueezy-mcp .
docker run --rm -i -e LEMONSQUEEZY_API_KEY="your-api-key" yawlabs/lemonsqueezy-mcp

A matching Containerfile is provided for Podman users. It is generated from Dockerfile via npm run gen:containerfile. release.sh runs npm run check:containerfile in step 1, so a release fails if the two have drifted. This repo has no CI, so nothing checks a pull request for drift: run it yourself after editing Dockerfile.

Claude Code

Add to your MCP config:

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

Claude Desktop

Add to claude_desktop_config.json:

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

Yaw MCP

The Add to Yaw MCP button at the top adds the server without a key. Store the key in Yaw MCP's encrypted vault rather than as a plain env value:

yaw-mcp set lemonsqueezy env.LEMONSQUEEZY_API_KEY --secret

It prompts for the value without echoing it (or reads it from piped stdin) and writes only a ${secret:...} reference into ~/.yaw-mcp/bundles.json. The same works for LEMONSQUEEZY_TEST_API_KEY and LEMONSQUEEZY_SINK_ADMIN_TOKEN.

Yaw MCP also treats LEMONSQUEEZY_API_KEY_COMMAND as a credential, because its name contains KEY: yaw-mcp doctor flags a literal value as plaintext:, and the value is masked in captured stderr. That is expected. The variable holds a command line, not a key, so the flag is harmless, and you can store the command as a secret the same way to silence it.

Tools (64)

Users

• ls_get_user — Get the authenticated user

Stores

• ls_get_store — Get a store by ID
• ls_list_stores — List all stores (not gated by LEMONSQUEEZY_ALLOWED_STORE_IDS: returns every store the API key can see)

Customers

• ls_get_customer — Get a customer by ID
• ls_list_customers — List customers (filter by store, email)
• ls_create_customer — Create a customer
• ls_update_customer — Update a customer
• ls_archive_customer — Archive a customer

Products

• ls_get_product — Get a product by ID
• ls_list_products — List products (filter by store)

Variants

• ls_get_variant — Get a variant by ID
• ls_list_variants — List variants (filter by product)

Prices

• ls_get_price — Get a price by ID
• ls_list_prices — List prices (filter by variant)

Both annotate every price record with effective_unit_price, the cents actually charged per unit, and effective_unit_price_note, which says where that number came from; unit_price_is_not_charged or unit_price_is_per_package is added where it applies. Read effective_unit_price rather than unit_price, which is vestigial on tiered (volume / graduated) pricing, or a variant's price. The subscription-item reads apply the same annotation to prices embedded via include=price.

Files

• ls_get_file — Get a file by ID
• ls_list_files — List files (filter by variant)

Orders

• ls_get_order — Get an order by ID
• ls_list_orders — List orders (filter by store, email)
• ls_generate_order_invoice — Generate a PDF invoice
• ls_refund_order — Issue a refund

Order Items

• ls_get_order_item — Get an order item by ID
• ls_list_order_items — List order items (filter by order, product, variant)

Subscriptions

• ls_get_subscription — Get a subscription by ID
• ls_list_subscriptions — List subscriptions (filter by store, status, product, etc.)
• ls_update_subscription — Update (plan switch, pause, billing anchor, trial)
• ls_cancel_subscription — Cancel a subscription

Subscription Invoices

• ls_get_subscription_invoice — Get a subscription invoice by ID
• ls_list_subscription_invoices — List subscription invoices (filter by store, subscription, status)
• ls_generate_subscription_invoice — Generate a PDF invoice
• ls_refund_subscription_invoice — Issue a refund

Subscription Items

• ls_get_subscription_item — Get a subscription item by ID
• ls_list_subscription_items — List subscription items (filter by subscription, price)
• ls_update_subscription_item — Update quantity
• ls_get_subscription_item_usage — Get current billing period usage

Usage Records

• ls_get_usage_record — Get a usage record by ID
• ls_list_usage_records — List usage records (filter by subscription item)
• ls_create_usage_record — Report metered usage (increment or set)

Discounts

• ls_get_discount — Get a discount by ID
• ls_list_discounts — List discounts (filter by store)
• ls_create_discount — Create a discount code
• ls_delete_discount — Delete a discount

Discount Redemptions

• ls_get_discount_redemption — Get a discount redemption by ID
• ls_list_discount_redemptions — List redemptions (filter by discount, order)

License Keys

• ls_get_license_key — Get a license key by ID
• ls_list_license_keys — List license keys (filter by store, order, product)
• ls_update_license_key — Update activation limit, expiry, or disabled status

License Key Instances

• ls_get_license_key_instance — Get a license key activation by ID
• ls_list_license_key_instances — List activations (filter by license key)

Checkouts

• ls_get_checkout — Get a checkout by ID
• ls_list_checkouts — List checkouts (filter by store, variant)
• ls_create_checkout — Create a checkout URL (custom pricing, prefill, discounts)

Webhooks

• ls_get_webhook — Get a webhook by ID
• ls_list_webhooks — List webhooks (filter by store)
• ls_create_webhook — Create a webhook
• ls_update_webhook — Update a webhook
• ls_delete_webhook — Delete a webhook

License API

• ls_activate_license — Activate a license key (no API key required)
• ls_validate_license — Validate a license key (no API key required)
• ls_deactivate_license — Deactivate a license key instance (no API key required). Destructive on every call: rate-limited and audited, with the license key masked in the audit entry

Affiliates

• ls_get_affiliate — Get an affiliate by ID (commission rate, status, earnings)
• ls_list_affiliates — List affiliates (filter by user email). Not gated by LEMONSQUEEZY_ALLOWED_STORE_IDS: returns affiliates from every store the API key can see

Webhook sink (optional)

Bridge to a separate @yawlabs/lemonsqueezy-webhook-sink process so the agent can reconcile against webhooks that actually fired. Tools are always registered; if LEMONSQUEEZY_SINK_URL / LEMONSQUEEZY_SINK_ADMIN_TOKEN are unset, calls return a clear "not configured" error.

• ls_sink_events_list — List webhook events the sink has received (filter by since / type / limit)
• ls_sink_event_mark_processed — Mark a sink event as processed by your consumer (idempotent)
• ls_sink_stats — Get total events, unprocessed count, and last-received timestamp

Features

• API coverage — 58 tools across 20 LemonSqueezy API resources, 3 License API tools, and 3 bridge tools to an optional @yawlabs/lemonsqueezy-webhook-sink for webhook reconciliation (64 in total)
• JSON:API support — Pagination on every ls_list_* tool, filters on every one but ls_list_stores, and relationship inclusion (include) on every ls_get_* / ls_list_* tool except ls_get_user and ls_get_subscription_item_usage
• Zero runtime dependencies — Single bundled file for instant npx startup
• License API — Activate, validate, and deactivate license keys without an API key
• MCP annotations — Every tool declares read-only, destructive, and idempotent hints
• Retry with backoff — for LemonSqueezy API calls (the ls_sink_* tools make a single attempt): a 429 is retried for every method, including POSTs such as refunds and License API calls, after waiting for the server's Retry-After (1s if it is missing or unparseable). This relies on a 429 meaning the request was rejected before LemonSqueezy acted on it. If Retry-After is over 30s, or the wait would pass the overall deadline, the 429 is returned instead. 5xx responses, timeouts and network errors are retried only for idempotent methods (GET, DELETE), with exponential backoff and jitter; a POST or PATCH that hits one is not retried. Up to 4 attempts, 30s per attempt, and no new attempt or wait is started after 90s
• Guardrails — opt-in store allowlist, refund cap, destructive-call rate limit, authority-class disable (LEMONSQUEEZY_DISABLE_CLASSES), and per-authority-class rate limits (LEMONSQUEEZY_RATE_LIMIT_PER_CLASS)
• Audit log MCP Resource — lemonsqueezy://audit-log exposes the last 1000 destructive-call entries as application/x-ndjson for clients without stderr access
• Structured logging — opt-in JSON logs to stderr with selectable levels (error, audit, all)

Configuration

All configuration is via environment variables. The management-API tools need one of LEMONSQUEEZY_API_KEY_COMMAND, LEMONSQUEEZY_TEST_API_KEY or LEMONSQUEEZY_API_KEY (ch