Lemon Squeezy MCP Server

Demo GIF showing the MCP server in action

📖 About

Give your AI assistant direct access to your payment and subscription data.

This server acts as a bridge between your AI assistant (like VS Code, Claude Desktop, or any MCP-compatible client) and your Lemon Squeezy account. Instead of manually logging into dashboards, searching for orders, and copy-pasting details, you can simply ask your AI questions like:

• "What was the last sale?"
• "Is subscription #12345 still active?"
• "Find all customers named 'Alice'"

Your AI will query the data securely and give you an instant answer, right in your code editor.

🌱 Beginner Level: Getting Started

Who is this for? You are new to CLI tools or just want to get this running quickly with minimal fuss.

1. Prerequisites

Before you start, make sure you have these two things installed on your computer:

• Node.js (Version 18 or higher): This is the software that runs the server. Download Node.js here.
• A Lemon Squeezy Account: You need an account to get the data. Sign up here.

2. Get Your API Key

Think of this as your password for the server.

1. Log in to your Lemon Squeezy Dashboard.
2. Go to Settings -> API.
3. Click Create API Key.
4. Copy the key (it starts with ls_...). Keep this safe!

3. Quick Installation

Open your terminal (Command Prompt on Windows, Terminal on Mac) and run these commands one by one:

# 1. Download the project
git clone https://github.com/IntrepidServicesLLC/lemonsqueezy-mcp-server.git
cd lemonsqueezy-mcp-server

# 2. Install the necessary files
npm install

# 3. Build the server
npm run build

4. Connect to Your AI Editor

The exact steps depend on which AI editor you're using. Here are the most common:

One-copy-paste setup (Claude Desktop / Cursor / npx):
Add this to your MCP config file (e.g. claude_desktop_config.json or Cursor MCP settings). Replace YOUR_KEY_HERE with your Lemon Squeezy API key.

"mcpServers": {
  "lemonsqueezy": {
    "command": "npx",
    "args": ["-y", "lemonsqueezy-mcp-server"],
    "env": {
      "LEMONSQUEEZY_API_KEY": "YOUR_KEY_HERE"
    }
  }
}

(Requires the package to be published on npm. For local development, use the path-based config below.)

For VS Code (local path):

1. Open VS Code Settings
2. Go to Extensions → MCP
3. Add a new MCP server with:
   • Command: node
   • Args: ["/absolute/path/to/lemonsqueezy-mcp-server/dist/index.js"]
   • Env: {"LEMONSQUEEZY_API_KEY": "your_api_key_here"}

For Claude Desktop (local path):

1. Edit ~/Library/Application Support/Claude/claude_desktop_config.json (Mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows)
2. Add the same configuration as above (command node, args with full path to dist/index.js)
3. Restart Claude Desktop

For Other MCP Clients: Refer to your client's documentation for adding MCP servers. The server runs via node /path/to/dist/index.js with the LEMONSQUEEZY_API_KEY environment variable set.

After configuring, restart your AI editor and try asking: "Show me my last 5 orders."

Trusted local and guarded access

The dist/index.js stdio setup above is for a trusted local merchant operator. It exposes the full legacy catalog, including tools that can change Lemon Squeezy data. Do not use that entry point as a customer-facing or delegated agent connector.

For delegated, read-only access, a trusted host must create the separate guarded server with createGuardedServer(provider, expectedEnvironment). The host supplies and verifies a scoped grant outside MCP tool arguments. The guarded server exposes only get_billing_summary and get_subscription_status when the grant permits them. See guarded connector setup, the exact tool catalog, and support and security reporting.

For self-hosted remote callers, use the separate authenticated Streamable HTTP entry point and the remote guarded setup and runnable example. The example includes an offline MCP client smoke test and an optional local check with your own Lemon Squeezy test-mode key. Its fixture is not a hosted identity or grant service.

🚀 Medium User Level: Basic Usage & Configuration

Who is this for? You are comfortable with config files, environment variables, and want to customize how the server works.

Philosophy: "Sensible Defaults"

This server is designed to work out of the box with just one required setting: your LEMONSQUEEZY_API_KEY. Everything else is optional and has pre-configured defaults that work for 90% of users.

Configuration Options

You can configure the server using Environment Variables in your MCP settings or a .env file.

Common Tasks

1. Using Test Mode If you want to develop without touching real money, generate a "Test API Key" in Lemon Squeezy and use LEMONSQUEEZY_TEST_API_KEY. The server will automatically prioritize the live key if both are present, so remove the live key to force test mode.

2. Enabling Salesforce Integration (Bonus) Want to sync customers to your CRM? Add these variables:

• SALESFORCE_USERNAME
• SALESFORCE_PASSWORD
• SALESFORCE_TOKEN (Security Token)

The tools for Salesforce (like sync_customer_to_crm) will automatically appear in your AI's toolkit.

Troubleshooting

• "Command not found": Ensure you ran npm run build after installing.
• "Authentication Error": Double-check your API key. Did you copy an extra space?
• Logs: The server outputs logs to the "MCP Log" window in your editor. Check there for specific error messages.

🛠️ Advanced User Level: Technical Documentation

Who is this for? Developers, Architects, and DevOps engineers looking for deep technical details, architecture diagrams, security compliance, and deployment strategies.

Containers: This repo has both a Containerfile and a Dockerfile with the same build. The Dockerfile exists so registries (e.g. Smithery) and CI that look for the filename Dockerfile can discover and build the image. You can build with Podman or Docker; see CONTAINERS.md for why both exist and how to build.

For a comprehensive breakdown of the system architecture, code modules, security protocols, and enterprise deployment guides, please refer to the:

👉 Technical Solution Design Document (TSD)

The TSD covers:

• System Architecture & Diagrams
• Module Interflows & Data Paths
• Security & Compliance (AWS Secrets Manager, etc.)
• Deployment (Docker/OCI Containers)
• Risk Mitigation Strategies