# LemonSqueezy MCP Server [Health: Active]

**Category:** 🛒 E-Commerce  
**Repository:** https://github.com/YawLabs/lemonsqueezy-mcp  
**GitHub Stars:** 3  
**npm Downloads (last month):** 1139  
**Views:** 7  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/lemonsqueezy-mcp-server-2

## Description
LemonSqueezy MCP server for managing your store from AI assistants

## Tools
Capabilities this server exposes over MCP:

- **ls_get_user** — Get the authenticated user's information including name, email, and avatar.
- **ls_get_store** — Get a specific store by ID, including name, slug, currency, and sales statistics.
- **ls_list_stores** — List all stores for the authenticated user. Results are paginated — check meta.page in the response for currentPage, lastPage, and total. Cross-store note: LEMONSQUEEZY_ALLOWED_STORE_IDS does NOT gate this tool -- it has no storeId field and no parent ID filter to scope by, so it returns every store the API key can see, including stores outside the allowlist. Pair with a scoped LemonSqueezy API key for true cross-store enforcement -- the API key's visibility is the true boundary.
- **ls_get_customer** — Get a specific customer by ID, including name, email, city, country, MRR, total revenue, and customer portal URL.
- **ls_list_customers** — List all customers, optionally filtered by store or email. Results are paginated — check meta.page in the response for currentPage, lastPage, and total.
- **ls_create_customer** — Create a new customer in a store.
- **ls_update_customer** — Update an existing customer's name, email, city, region, country, or status. The only supported status value is 'archived'; setting it here is the same operation as ls_archive_customer and is treated as destructive (rate-limited and audited). Other field edits are not.
- **ls_archive_customer** — Archive a customer. Sets their status to 'archived'. This is reversible by updating their status back.
- **ls_get_product** — Get a specific product by ID, including name, description, price, and status.
- **ls_list_products** — List all products, optionally filtered by store. Results are paginated — check meta.page in the response for currentPage, lastPage, and total.
- **ls_get_variant** — Get a specific product variant by ID, including billing interval and trial settings. WARNING: do NOT read `price` as the amount charged. For usage-based, per-seat or otherwise tiered variants it is vestigial and commonly reads the same value across products that bill very differently. The authoritative per-unit price lives on the variant's PRICE resource -- call ls_list_prices with this variantId, take the newest record by `created_at`, and read its `effective_unit_price`.
- **ls_list_variants** — List all variants, optionally filtered by product. Results are paginated — check meta.page in the response for currentPage, lastPage, and total. WARNING: do NOT read `price` as the amount charged -- for usage-based, per-seat or otherwise tiered variants it is vestigial and commonly reads the same value across products that bill very differently. The authoritative per-unit price lives on each variant's PRICE resource: call ls_list_prices with the variantId, take the newest record by `created_at`, and read its `effective_unit_price`. Cross-store note: when LEMONSQUEEZY_ALLOWED_STORE_IDS is set, this tool requires at least one of: productId. Even with that set, Pair with a scoped LemonSqueezy API key for true cross-store enforcement -- the API key's visibility is the true boundary.
- **ls_get_price** — Get a specific price by ID, including amount, currency, and billing interval. Every record is annotated with `effective_unit_price` (cents actually charged per unit) and `effective_unit_price_note`. READ THAT, not `unit_price`: on a tiered scheme (volume/graduated) `unit_price` is vestigial and is NOT the charged amount -- the real per-unit price lives in `tiers[]`, and such records also carry `unit_price_is_not_charged: true`. On `package` pricing `unit_price` IS charged, but it buys a block of `package_size` units, so `effective_unit_price` reports the per-unit figure and the record carries `unit_price_is_per_package: true`.
- **ls_list_prices** — List all prices, optionally filtered by variant. Results are paginated — check meta.page in the response for currentPage, lastPage, and total. Every record is annotated with `effective_unit_price` (cents actually charged per unit) and `effective_unit_price_note`. READ THAT, not `unit_price`: on a tiered scheme (volume/graduated) `unit_price` is vestigial and is NOT the charged amount -- the real per-unit price lives in `tiers[]`, and such records also carry `unit_price_is_not_charged: true`. On `package` pricing `unit_price` IS charged, but it buys a block of `package_size` units, so `effective_unit_price` reports the per-unit figure and the record carries `unit_price_is_per_package: true`. NOTE that several price records can exist per variant; the CURRENT one is the newest by `created_at` (results are sorted newest-first). Cross-store note: when LEMONSQUEEZY_ALLOWED_STORE_IDS is set, this tool requires at least one of: variantId. Even with that set, Pair with a scoped LemonSqueezy API key for true cross-store enforcement -- the API key's visibility is the true boundary.
- **ls_get_file** — Get a specific file by ID, including name, size, download URL, and associated variant.
- **ls_list_files** — List all files, optionally filtered by variant. Results are paginated — check meta.page in the response for currentPage, lastPage, and total. Cross-store note: when LEMONSQUEEZY_ALLOWED_STORE_IDS is set, this tool requires at least one of: variantId. Even with that set, Pair with a scoped LemonSqueezy API key for true cross-store enforcement -- the API key's visibility is the true boundary.
- **ls_get_order** — Get a specific order by ID, including status, total, currency, customer info, and payment details.
- **ls_list_orders** — List all orders, optionally filtered by store or user email. Results are paginated — check meta.page in the response for currentPage, lastPage, and total.
- **ls_generate_order_invoice** — Generate a PDF invoice for an order. Returns a download URL for the invoice.
- **ls_refund_order** — Issue a refund for an order. This is irreversible — the refund amount is in cents (e.g. 1000 = $10.00).
- **ls_get_order_item** — Get a specific order item by ID, including product name, variant, price, and quantity.
- **ls_list_order_items** — List all order items, optionally filtered by order or product. Results are paginated — check meta.page in the response for currentPage, lastPage, and total. Cross-store note: when LEMONSQUEEZY_ALLOWED_STORE_IDS is set, this tool requires at least one of: orderId, productId, variantId. Even with that set, Pair with a scoped LemonSqueezy API key for true cross-store enforcement -- the API key's visibility is the true boundary.
- **ls_get_subscription** — Get a specific subscription by ID, including status, billing interval, renewal date, and customer info.
- **ls_list_subscriptions** — List all subscriptions, optionally filtered by store, order, product, variant, or status. Results are paginated — check meta.page in the response for currentPage, lastPage, and total.
- **ls_update_subscription** — Update a subscription. Can change the variant (plan switch), pause/unpause, set billing anchor, or update invoice details. Pausing (`pause: 'void'` or `'free'`), switching plan (`variantId`), changing the billing anchor (`billingAnchor`), invoicing immediately (`invoiceImmediately: true`), or changing the trial end (`trialEndsAt`) changes what the customer pays or when, and is treated as destructive (rate-limited and audited); resuming (`pause: 'resume'`), un-cancelling (`cancelled: false`), `invoiceImmediately: false` and `disableProrations` are not. Use ls_cancel_subscription for cancellation.
- **ls_cancel_subscription** — Cancel a subscription. The subscription remains active until the end of the current billing period, then expires.
- **ls_get_subscription_invoice** — Get a specific subscription invoice by ID, including status, total, billing reason, and payment details.
- **ls_list_subscription_invoices** — List all subscription invoices, optionally filtered by store, subscription, or status. Results are paginated — check meta.page in the response for currentPage, lastPage, and total.
- **ls_generate_subscription_invoice** — Generate a PDF invoice for a subscription invoice. Returns a download URL.
- **ls_refund_subscription_invoice** — Issue a refund for a subscription invoice. This is irreversible — the refund amount is in cents (e.g. 1000 = $10.00).
- **ls_get_subscription_item** — Get a specific subscription item by ID, including quantity, pricing, and associated subscription. Pass `include=price` for the price record behind it; embedded price records are annotated with `effective_unit_price` (cents actually charged per unit) -- read that, not the record's `unit_price`, which is vestigial on tiered pricing and per-package on package pricing.
- **ls_list_subscription_items** — List all subscription items, optionally filtered by subscription or price. Results are paginated — check meta.page in the response for currentPage, lastPage, and total. Pass `include=price` for the price records behind them; embedded price records are annotated with `effective_unit_price` (cents actually charged per unit) -- read that, not a record's `unit_price`, which is vestigial on tiered pricing and per-package on package pricing. Cross-store note: when LEMONSQUEEZY_ALLOWED_STORE_IDS is set, this tool requires at least one of: subscriptionId, priceId. Even with that set, Pair with a scoped LemonSqueezy API key for true cross-store enforcement -- the API key's visibility is the true boundary.
- **ls_update_subscription_item** — Update a subscription item's quantity. Used for seat-based or quantity-based billing.
- **ls_get_subscription_item_usage** — Get the current usage for a metered subscription item within the current billing period.
- **ls_get_usage_record** — Get a specific usage record by ID, including quantity and action type.
- **ls_list_usage_records** — List all usage records, optionally filtered by subscription item. Results are paginated — check meta.page in the response for currentPage, lastPage, and total. Cross-store note: when LEMONSQUEEZY_ALLOWED_STORE_IDS is set, this tool requires at least one of: subscriptionItemId. Even with that set, Pair with a scoped LemonSqueezy API key for true cross-store enforcement -- the API key's visibility is the true boundary.
- **ls_create_usage_record** — Report usage for a metered subscription item. Use 'increment' action to add to the current usage, or 'set' to replace it.
- **ls_get_discount** — Get a specific discount by ID, including code, amount, type, and usage limits.
- **ls_list_discounts** — List all discounts, optionally filtered by store. Results are paginated — check meta.page in the response for currentPage, lastPage, and total.
- **ls_create_discount** — Create a new discount code. Supports percentage or fixed amount discounts with optional duration and usage limits.
- **ls_delete_discount** — Permanently delete a discount. This is irreversible.
- **ls_get_discount_redemption** — Get a specific discount redemption by ID, showing when and where a discount was used.
- **ls_list_discount_redemptions** — List all discount redemptions, optionally filtered by discount or order. Results are paginated — check meta.page in the response for currentPage, lastPage, and total. Cross-store note: when LEMONSQUEEZY_ALLOWED_STORE_IDS is set, this tool requires at least one of: discountId, orderId. Even with that set, Pair with a scoped LemonSqueezy API key for true cross-store enforcement -- the API key's visibility is the true boundary.
- **ls_get_license_key** — Get a specific license key by ID, including key value, status, activation limit, and expiry date.
- **ls_list_license_keys** — List all license keys, optionally filtered by store, order, or product. Results are paginated — check meta.page in the response for currentPage, lastPage, and total.
- **ls_update_license_key** — Update a license key's activation limit, expiry date, or disabled status. Setting `disabled: true`, changing `activationLimit`, or changing `expiresAt` can revoke customer access and is treated as destructive (rate-limited and audited); `disabled: false` alone is not.
- **ls_get_license_key_instance** — Get a specific license key instance (activation) by ID, including instance name and creation date.
- **ls_list_license_key_instances** — List all license key instances (activations), optionally filtered by license key. Results are paginated — check meta.page in the response for currentPage, lastPage, and total. Cross-store note: when LEMONSQUEEZY_ALLOWED_STORE_IDS is set, this tool requires at least one of: licenseKeyId. Even with that set, Pair with a scoped LemonSqueezy API key for true cross-store enforcement -- the API key's visibility is the true boundary.
- **ls_get_checkout** — Get a specific checkout by ID, including URL, expiry, and custom data.
- **ls_list_checkouts** — List all checkouts, optionally filtered by store or variant. Results are paginated — check meta.page in the response for currentPage, lastPage, and total.
- **ls_create_checkout** — Create a new checkout URL for a product variant. Returns a URL where the customer can complete their purchase. Supports custom pricing, prefilled customer data, and checkout customization.
- **ls_get_webhook** — Get a specific webhook by ID, including URL, events, and last sent timestamp.
- **ls_list_webhooks** — List all webhooks, optionally filtered by store. Results are paginated — check meta.page in the response for currentPage, lastPage, and total.
- **ls_create_webhook** — Create a new webhook to receive event notifications. The signing secret is returned only once — save it immediately.
- **ls_update_webhook** — Update an existing webhook's URL, events, or secret. Setting `secret` rotates the signing secret and breaks signature verification on the receiver until they update their copy -- this is treated as destructive (rate-limited and audited).
- **ls_delete_webhook** — Permanently delete a webhook. This is irreversible.
- **ls_activate_license** — Activate a license key for an instance. Does not require an API key — uses the license key itself for auth.
- **ls_validate_license** — Validate a license key or specific instance. Does not require an API key — uses the license key itself for auth.
- **ls_deactivate_license** — Deactivate a license key instance, revoking that instance's access. Destructive: rate-limited and audited, with the license key masked in the audit entry. Does not require an API key — uses the license key itself for auth.
- **ls_get_affiliate** — Get a specific affiliate by ID, including commission rate, status, and earnings.
- **ls_list_affiliates** — List all affiliates for the authenticated user's stores, optionally filtered by user email. Results are paginated — check meta.page in the response for currentPage, lastPage, and total. Cross-store note: LEMONSQUEEZY_ALLOWED_STORE_IDS does NOT gate this tool -- it has no storeId field and no parent ID filter to scope by, so it returns affiliates tied to every store the API key can see, including non-allowed ones. Pair with a scoped LemonSqueezy API key for true cross-store enforcement -- the API key's visibility is the true boundary.
- **ls_sink_events_list** — List webhook events the sink has received, optionally filtered. Use `since` (received_at timestamp, exclusive) to checkpoint. Requires the sink at LEMONSQUEEZY_SINK_URL with LEMONSQUEEZY_SINK_ADMIN_TOKEN.
- **ls_sink_event_mark_processed** — Mark a sink event as processed by your consumer. Idempotent.
- **ls_sink_stats** — Get sink totals: total events, unprocessed count, last-received timestamp.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "lemonsqueezy-mcp-server": {
    "command": "npx",
    "args": ["-y","@yawlabs/lemonsqueezy-mcp@latest"],
    "env": {
      "LEMONSQUEEZY_API_KEY": ""
    }
  }
}
```

**Requires environment variables:** `LEMONSQUEEZY_API_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What LemonSqueezy MCP Server does

LemonSqueezy MCP Server gives MCP-compatible assistants access to Lemon Squeezy store data and selected management operations. It can retrieve the authenticated user, inspect stores, and work with customers, products, variants, prices, downloadable files, orders, order items, subscriptions, and subscription invoices.

Read operations cover individual resources and paginated lists. List tools support filters such as store, product, variant, customer email, order, subscription, or status where applicable. Write operations include creating and editing customers, archiving customers, updating subscriptions, cancelling subscriptions, and issuing order or subscription-invoice refunds. Invoice tools generate PDF download URLs.

## How it works

The package runs as an MCP process using stdio transport and forwards tool requests to the Lemon Squeezy API. An assistant can translate a natural-language request into several calls—for example, locating a subscription, inspecting its plan and invoices, and then presenting the relevant figures.

Pagination metadata is returned by list operations; clients should inspect `meta.page` for the current page, final page, and total. Price resources include an `effective_unit_price` value. For tiered pricing, `unit_price` is not the amount charged, while package pricing represents a block of units; the annotated effective value is the safer field for per-unit calculations. When multiple prices exist for a variant, the newest record by `created_at` is the current one.

Destructive actions have important operational consequences. Order and subscription-invoice refunds are irreversible and use cents as the amount. Subscription cancellation leaves the subscription active through the current billing period. Subscription plan changes, pauses, billing-anchor changes, immediate invoicing, and trial-end changes can affect what a customer pays or when they pay.

## Setup and configuration

Install and run the package with:

```bash
npx -y @yawlabs/lemonsqueezy-mcp@latest
```

Node.js 22 or newer is required. Set `LEMONSQUEEZY_API_KEY` to a key from the Lemon Squeezy dashboard. Claude Desktop and Claude Code can launch the package with `npx`, passing the API key through the MCP configuration's `env` object.

A Dockerfile is included for a stdio container deployment. The documented image uses Node 22 Alpine and runs as the non-root `node` user; the container must receive the API key and an interactive stdin connection. A matching Podman-oriented Containerfile is also available. Smithery can install the package and prompt for environment variables.

## Tools and capabilities

Available tool groups include:

- User and store inspection, including store metadata and sales statistics.
- Customer lookup, listing, creation, editing, and reversible archiving.
- Product, variant, price, and downloadable-file discovery.
- Order and order-item lookup, filtered listing, PDF invoice generation, and refunds.
- Subscription and invoice lookup, filtering, plan changes, pausing, cancellation, invoice generation, and refunds.

Store filters and allowlists require care. `ls_list_stores` returns every store visible to the API key and is not restricted by `LEMONSQUEEZY_ALLOWED_STORE_IDS`. For several cross-store list operations, setting an allowlist requires a narrowing identifier such as `productId`, `variantId`, `orderId`, or `storeId`, depending on the tool. A scoped Lemon Squeezy API key remains the actual boundary for store visibility.

_Full upstream README: https://allmcps.com/mcp/lemonsqueezy-mcp-server-2/readme_

