lemonsqueezy-mcp-server

Lemon Squeezy MCP サーバー

📖 概要

AI アシスタントから決済データやサブスクリプションデータに直接アクセスできるようにします。

このサーバーは、AI アシスタント（VS Code、Claude Desktop、または MCP 対応クライアントなど）と Lemon Squeezy アカウントをつなぐ橋渡し役として機能します。ダッシュボードに手動でログインして注文を検索し、詳細をコピー＆ペーストする代わりに、次のような質問を AI にするだけで済みます。

• 「最後の販売は何でしたか？」
• 「サブスクリプション #12345 はまだ有効ですか？」
• 「名前が『Alice』の顧客をすべて探して」

AI がデータを安全に照会し、コードエディター上で即座に回答します。

---

🌱 初心者向け：使い始める

対象者： コマンドラインツールを初めて使う方や、手間をかけずにすぐ実行したい方。

1. 前提条件

始める前に、次の2つがコンピューターにインストールされていることを確認してください。

• 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つずつ実行します。

# 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. 拡張機能 → MCPに移動します
3. 次の設定で新しいMCPサーバーを追加します：
   • コマンド： node
   • 引数： ["/absolute/path/to/lemonsqueezy-mcp-server/dist/index.js"]
   • 環境変数： {"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 のデータを変更できるツールを含め、従来のカタログ全体を公開します。このエントリーポイントは、顧客向けまたは委任エージェント用のコネクターとして使用しないでください。

委任された読み取り専用アクセスでは、信頼されたホストが createGuardedServer(provider, expectedEnvironment) を使用して、別個の保護されたサーバーを作成する必要があります。ホストは MCP ツールの引数の外部でスコープ付き許可を提供し、検証します。許可によって認められている場合に限り、保護されたサーバーは get_billing_summary と get_subscription_status のみを公開します。保護されたコネクターのセットアップ、正確なツールカタログ、サポートとセキュリティに関する報告を参照してください。

セルフホスト型のリモート呼び出し元には、認証付きの Streamable HTTP エントリーポイントと、リモート保護セットアップおよび実行可能な例を使用してください。この例には、オフラインの MCP クライアントのスモークテストと、独自の Lemon Squeezy テストモードキーを使ったオプションのローカルチェックが含まれています。このフィクスチャは、ホスト型の ID サービスや許可サービスではありません。

---

🚀 中級ユーザーレベル：基本的な使い方と設定

対象となる方： 設定ファイルや環境変数に慣れていて、サーバーの動作をカスタマイズしたい方。

設計方針：「妥当なデフォルト」

このサーバーは、必須設定が LEMONSQUEEZY_API_KEY 1つだけで、すぐに使えるように設計されています。それ以外の設定はすべて任意で、ユーザーの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 の両方があります。レジストリ（Smithery など）や、ファイル名 Dockerfile を探してイメージを検出・ビルドする CI で利用できるよう、Dockerfile を用意しています。Podman または Docker でビルドできます。両方のファイルが存在する理由とビルド方法については、CONTAINERS.md をご覧ください。

システムアーキテクチャ、コードモジュール、セキュリティプロトコル、エンタープライズ向けデプロイガイドの詳細については、以下をご覧ください。

👉 技術ソリューション設計ドキュメント（TSD）

TSD では、以下について説明しています。

• システムアーキテクチャと図
• モジュール間のデータフローと経路
• セキュリティとコンプライアンス（AWS Secrets Manager など）
• デプロイ（Docker／OCI コンテナ）
• リスク軽減戦略