salonrunner-mcp

salonrunner-mcp

個人の SalonRunner / Rosy Salon Software クライアントアカウントを通じて、AI アシスタントがサロンの予約を検索、予約、キャンセルできるようにする MCP サーバーです。多くのサロンが利用している予約サイトと同じものです。

セルフホスト可能です。独自のインスタンスをデプロイします。認証情報を手元のマシンに保存したまま、ツールとしてローカルで実行することも（Claude Desktop、Cursor、Copilot CLI）、claude.ai用のリモートコネクターとして実行することもできます。リモートコネクターの場合は、コネクターのログイン画面で SalonRunner アカウントにログインします。

⚠️ 非公式であり、文書化されていないエンドポイントを使用します。個人利用のみを対象としています。DISCLAIMER.mdをお読みください。

ツール

動作の仕組み

list/find/book/cancel
        │
   this server ──login──► app.salonrunner.com  (session cookie)
        │      ──authv2─► customer JWT (30 min, auto-refreshed)
        │      ──reads──► app.rosysalonsoftware.com/api/v2  (Bearer JWT)
        └──────writes───► /customer/appointments/{book,cancel}.json  (cookie)

customerIdはログイン後にアカウントから検出され、corporateIdはJWTから読み取られます。 空き状況は、プロバイダーごとのサービス所要時間とサロンの時間枠の間隔（SALONRUNNER_SLOT_MINUTES、デフォルトは15分）に基づいて計算されます。

設定

実行方法は2つあり、サロンの認証情報の取得方法がそれぞれ異なります。

• ローカル（stdio）： 認証情報は環境（.env）から取得します。
• リモート（HTTP、claude.ai）： 認証情報はコネクターのログイン画面で入力し、トークンに暗号化して保存します。サーバーの環境変数にサロンの認証情報を設定する必要はありません。

HTTPモードでは、サロンID、ユーザー名、パスワードをログイン画面で入力します（実際の SalonRunner ログインで検証されます）。これらはOAuthトークンに暗号化して保存されるため、1つのデプロイで複数のサロンに対応でき、サーバーにサロンの機密情報を保存する必要もありません。

オプションA — ローカル（Claude Desktop / Cursor / Copilot CLI）

npmでsalonrunner-mcpとして公開されています。グローバルにインストールします。

npm install -g salonrunner-mcp

次に、クライアントでsalonrunner-mcpコマンドを指定します（ビルドや絶対パスは不要です）。Claude Desktop（claude_desktop_config.json）の場合：

{
  "mcpServers": {
    "salonrunner": {
      "command": "salonrunner-mcp",
      "env": {
        "SALONRUNNER_SALON_ID": "21248",
        "SALONRUNNER_USERNAME": "[email protected]",
        "SALONRUNNER_PASSWORD": "your-password"
      }
    }
  }
}

グローバルにインストールしたくない場合は、同じenvを使い、"command": "npx"と"args": ["-y", "salonrunner-mcp"]を指定してください。

npm install && npm run build

ホスティングもOAuthも不要です。認証情報は手元のマシンに保存されます。claude.aiが不要な場合におすすめです。

オプションB — リモート（claude.ai カスタムコネクター）

claude.aiで使用できるのはリモートMCPサーバーのみのため、独自のインスタンスをデプロイします。

Fly.io にデプロイする

fly launch --no-deploy          # pick a unique app name; creates the app
fly secrets set \
  SESSION_SIGNING_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))") \
  PUBLIC_URL=https://YOUR-APP.fly.dev
fly deploy
fly scale count 1               # in-memory MCP sessions: keep a single instance

ここではサロンの認証情報は設定されていません。ユーザーがログイン画面で入力します。SESSION_SIGNING_KEY がない場合、サーバーは起動を拒否します。認証情報は実際の SalonRunner ログインで検証された後、暗号化されて（署名済みの）トークンに埋め込まれます。このトークンは claude.ai に保存されるため、アプリは利用していない間はゼロまでスケールダウンし、認証は一度だけで済みます。コールドスタート（約3秒）は透過的に処理され、再認証を求められることはありません。

claude.ai で接続する

1. Settings → Connectors → Add custom connector。
2. URL：https://YOUR-APP.fly.dev/mcp
3. Claude がコネクターのログイン画面を開くので、サロン ID、ユーザー名、パスワードを入力します。
4. 6つのツールがチャットに表示されます。

リモートサーバーをローカルで実行する（テスト）

SESSION_SIGNING_KEY=local-dev-please-change PUBLIC_URL=http://localhost:8787 npm run start:http

セキュリティモデル

独立した2つの認証レイヤーがあります。

1. claude.ai ↔ このサーバー — OAuth 2.1（PKCE + 動的クライアント登録）。ログイン画面でユーザーを実際の SalonRunner ログインによって認証します。その後、認証情報はAES-GCM で暗号化され、HMAC 署名付きトークンに埋め込まれます（SESSION_SIGNING_KEY を鍵として使用）。サーバー側にセッションストアがないため、再起動後も、ゼロまでスケールダウンした後も認証が維持されます。
2. このサーバー ↔ SalonRunner — ログイン → セッション Cookie → 短期間有効な JWT の順に処理され、呼び出し元のトークンから復号した認証情報を使って自動更新されます。

サーバーはサロンの認証情報を保存しません。認証情報は各ユーザーのトークン内に暗号化されて保持され、リクエストごとにメモリ上でのみ復号されます。1つのデプロイで複数のサロンに対応できます。トークンが漏洩しても個別に無効化できません。SESSION_SIGNING_KEY をローテーションするとすべてのトークンが無効になり、全員が認証情報を再入力する必要があります。SESSION_SIGNING_KEY を秘密に保ち、HTTPS 経由でのみ提供してください。

注意事項と制限

• 非公開の顧客向けエンドポイントを使用しているため、予告なく変更される可能性があります。ベース URL は設定可能なので、すぐに対応できます。
• 実際の予約やキャンセルには、サロンのキャンセルポリシーに基づく手数料が発生します。ツールは実行前にサービス、担当者、日時を表示します。まず SALONRUNNER_READ_ONLY=true を設定して実行することをご検討ください。
• 正確な空き状況を確認するには、SALONRUNNER_SLOT_MINUTES をサロンの予約枠に合わせる必要があります（デフォルトは15分です）。
• 公式に文書化されているパートナー専用の Rosy Salon Software API（api.salonrunner.com）は別製品で、サロンが発行する ApiKey が必要です。このプロジェクトでは使用しません。

ライセンス

MIT — LICENSE を参照してください。保証はありません。