lemonsqueezy-mcp-server

Lemon Squeezy MCP 服务

📖 关于

让你的 AI 助手直接访问付款和订阅数据。

此服务充当你的 AI 助手（例如 VS Code、Claude Desktop 或任何兼容 MCP 的客户端）与 Lemon Squeezy 账户之间的桥梁。你无需手动登录控制面板、搜索订单并复制粘贴详情，只需向 AI 提问，例如：

• “最近一笔销售是什么时候？”
• “订阅 #12345 仍处于有效状态吗？”
• “查找所有名为 ‘Alice’ 的客户”

AI 会安全地查询数据，并直接在代码编辑器中即时为你解答。

---

🌱 入门：开始使用

适合哪些人？ 初次使用命令行工具，或只想轻松快速完成安装的用户。

1. 前提条件

开始之前，请确保你的电脑已安装以下两项：

• Node.js（18 或更高版本）： 用于运行服务的软件。在此下载 Node.js。
• Lemon Squeezy 账户： 你需要一个账户来获取数据。在此注册。

2. 获取 API 密钥

可以把它当作服务的密码。

1. 登录 Lemon Squeezy 控制面板。
2. 前往 Settings -> API。
3. 点击 Create API Key。
4. 复制密钥（以 ls_... 开头）。请妥善保管！

3. 快速安装

打开终端（Windows 上使用命令提示符，Mac 上使用终端），然后依次运行以下命令：

# 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. 连接到 AI 编辑器

具体步骤取决于你使用的 AI 编辑器。以下是最常见的方式：

一键复制粘贴配置（Claude Desktop / Cursor / npx）：
将以下内容添加到 MCP 配置文件中（例如 claude_desktop_config.json 或 Cursor MCP 设置）。将 YOUR_KEY_HERE 替换为你的 Lemon Squeezy API 密钥。

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

（需要先将软件包发布到 npm。本地开发请使用下方基于路径的配置。）

VS Code（本地路径）：

1. 打开 VS Code 设置
2. 前往 Extensions → MCP
3. 添加新的 MCP 服务，并填写以下内容：
   • Command： node
   • Args： ["/absolute/path/to/lemonsqueezy-mcp-server/dist/index.js"]
   • Env： {"LEMONSQUEEZY_API_KEY": "your_api_key_here"}

Claude Desktop（本地路径）：

1. 编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（Mac）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）
2. 添加与上述相同的配置（命令为 node，参数中填写 dist/index.js 的完整路径）
3. 重启 Claude Desktop

其他 MCP 客户端： 请参阅客户端文档，了解如何添加 MCP 服务。设置 LEMONSQUEEZY_API_KEY 环境变量后，可通过 node /path/to/dist/index.js 运行该服务。

完成配置后，重启 AI 编辑器并尝试询问：“显示最近 5 笔订单。”

可信本地访问与受保护访问

上面的 dist/index.js stdio 设置面向可信的本地商家运营人员。它会公开完整的旧版目录，其中包括可以更改 Lemon Squeezy 数据的工具。请勿将该入口点用作面向客户或委托 Agent 的连接器。

对于委托的只读访问，可信主机必须使用 createGuardedServer(provider, expectedEnvironment) 创建单独的受保护服务。主机在 MCP 工具参数之外提供并验证范围受限的授权。只有在授权允许时，受保护服务才会公开 get_billing_summary 和 get_subscription_status。请参阅受保护连接器设置、确切的工具目录以及支持与安全问题报告。

对于可自托管的远程调用方，请使用单独的、经过身份验证的 Streamable HTTP 入口点，并参阅远程受保护设置与可运行示例。该示例包含离线 MCP 客户端冒烟测试，以及使用你自己的 Lemon Squeezy 测试模式密钥进行的可选本地检查。其模拟数据不是托管身份或授权服务。

---

🚀 中级用户：基本用法与配置

适用对象： 熟悉配置文件和环境变量，并希望自定义服务的工作方式。

设计理念：“合理的默认设置”

此服务开箱即用，只需设置一个必填项：你的 LEMONSQUEEZY_API_KEY。其他所有设置均为可选项，并已预先配置好适用于 90% 用户的默认值。

配置选项

你可以在 MCP 设置中使用环境变量或通过 .env 文件配置服务。

变量	说明	默认值
LEMONSQUEEZY_API_KEY	必填。 你的正式 API 密钥。	-
LEMONSQUEEZY_TEST_API_KEY	可选。用于测试，不影响真实数据。	-
ENABLE_RESOURCES	设置为 true，让 AI 自动查看失败付款等“活动上下文”。	false
POLL_FAILED_PAYMENTS	设置为 true，每隔几分钟检查一次失败付款。	false

常见任务

1. 使用测试模式 如果你想在开发时避免动用真实资金，请在 Lemon Squeezy 中生成“Test API Key”，并使用 LEMONSQUEEZY_TEST_API_KEY。如果正式密钥和测试密钥同时存在，服务会自动优先使用正式密钥；因此，要强制使用测试模式，请移除正式密钥。

2. 启用 Salesforce 集成（额外功能） 想要将客户同步到 CRM？ 添加以下变量：

• SALESFORCE_USERNAME
• SALESFORCE_PASSWORD
• SALESFORCE_TOKEN（安全令牌）

Salesforce 工具（如 sync_customer_to_crm）会自动出现在你的 AI 工具集中。

故障排除

• “找不到命令”： 安装后，请确保已运行 npm run build。
• “身份验证错误”： 仔细检查你的 API 密钥。是否多复制了空格？
• 日志： 服务会在编辑器的“MCP Log”窗口中输出日志。请在那里查看具体的错误消息。

---

🛠️ 高级用户：技术文档

适用对象？ 希望深入了解技术细节、架构图、安全合规性和部署策略的开发者、架构师和 DevOps 工程师。

容器： 此仓库同时包含一个 Containerfile 和一个 Dockerfile，二者的构建方式相同。保留 Dockerfile 是为了让 Smithery 等注册表以及查找文件名 Dockerfile 的 CI 能够发现并构建镜像。你可以使用 Podman 或 Docker 构建；关于为何同时保留这两个文件以及如何构建，请参阅 CONTAINERS.md。

如需全面了解系统架构、代码模块、安全协议和企业级部署指南，请参阅：

👉 技术解决方案设计文档（TSD）

TSD 涵盖：

• 系统架构与图表
• 模块间流转与数据路径
• 安全与合规性（AWS Secrets Manager 等）
• 部署（Docker/OCI 容器）
• 风险缓解策略