smaregi-mcp

スマレジ API を Claude Code から操作するための MCP サーバーと Skills。

商品管理・売上確認・在庫操作・会員管理・店舗設定など、スマレジの各種 API を Claude Code の会話から直接利用できます。

Note: このプロジェクトはスマレジ株式会社の公式ツールではありません。スマレジ Developer Platform の公開 API 仕様をもとに作成した非公式の連携ツールです。

構成

smaregi-mcp/
├── MCP サーバー (src/, bin/)    ... APIを実際に叩く「手足」
└── Skills (skills/)             ... APIの使い方を知る「知識」

• MCP サーバー: 9つの汎用ツール（GET/POST/PUT/DELETE/PATCH + 管理系）を提供
• Skills: API リファレンス 63 ファイル + 操作ガイド 12 ファイル

対応 API

API	Skills	MCP
POS（商品・取引・会員・在庫・店舗等）	対応	対応
在庫管理（ロス・発注・入荷・出荷・棚卸）	対応	未対応 (*1)
ウェイター（メニュー・テーブル・注文・予約）	対応	未対応 (*1)
受注出荷（受注・出荷・決済）	対応	未対応 (*1)
タイムカード（打刻・勤怠・給与・日報）	対応	未対応 (*1)

*1: MCP サーバーのベースパスが /pos 固定のため。Skills のリファレンスは全 API 分を網羅済み。

セットアップ

前提条件

• Node.js 18 以上
• Claude Code インストール済み
• スマレジ Developer Platform でアプリ作成済み（クライアント ID / シークレット取得済み）

1. Skills のインストール

npx smaregi-mcp setup-skills

~/.claude/skills/smaregi-api-skill/ に API リファレンスと操作ガイドがインストールされます。

2. MCP サーバーの登録

~/.claude/settings.json の mcpServers に追加:

{
  "mcpServers": {
    "smaregi": {
      "command": "npx",
      "args": ["smaregi-mcp"]
    }
  }
}

3. Claude Code を再起動

4. 認証設定

Claude Code の会話で:

スマレジの認証設定をして

契約 ID・クライアント ID・クライアントシークレットを入力すると ~/.config/smaregi-mcp/config.json に保存されます。

5. 動作確認

スマレジの店舗一覧を取得して

ソースからビルドする場合

git clone https://github.com/fujioka0729/smaregi-mcp.git
cd smaregi-mcp
npm install
npm run build

MCP ツール一覧

ツール	説明
smaregi_api_get	GET リクエスト（データ取得）
smaregi_api_post	POST リクエスト（データ作成）
smaregi_api_put	PUT リクエスト（データ更新）
smaregi_api_delete	DELETE リクエスト（データ削除）
smaregi_api_patch	PATCH リクエスト（部分更新）
smaregi_api_list_paths	利用可能なエンドポイント一覧
smaregi_configure	認証情報設定
smaregi_auth_status	認証状態確認
smaregi_server_info	サーバー情報表示

Skills 構成

skills/smaregi-api-skill/
├── SKILL.md                    # スキル定義・全体目次
├── references/ (63 ファイル)    # API エンドポイント仕様書
│   ├── common-*                # 認証・Webhook
│   ├── pos-*                   # POS API
│   ├── inventory-*             # 在庫管理 API
│   ├── waiter-*                # ウェイター API
│   ├── order-*                 # 受注出荷 API
│   └── timecard-*              # タイムカード API
└── recipes/ (12 ファイル)       # 操作手順ガイド
    ├── product-operations.md   # 商品管理
    ├── transaction-operations.md # 取引操作
    ├── customer-operations.md  # 会員管理
    ├── stock-operations.md     # 在庫操作
    ├── store-operations.md     # 店舗管理
    ├── coupon-operations.md    # クーポン操作
    ├── inventory-management-operations.md # 在庫管理
    ├── waiter-operations.md    # ウェイター操作
    ├── order-management-operations.md     # 受注出荷操作
    ├── staff-timecard-operations.md       # タイムカード操作
    ├── webhook-setup.md        # Webhook 設定
    └── troubleshooting.md      # トラブルシューティング

スマレジアプリの作成

1. developers.smaregi.dev でアプリを新規登録（種別: Web アプリ）
2. 必要なスコープを有効化:
   • pos.products:read / pos.products:write
   • pos.customers:read / pos.customers:write
   • pos.stores:read
   • pos.transactions:read / pos.transactions:write
   • pos.staffs:read
   • pos.stock:read / pos.stock:write
3. クライアント ID / シークレットを控える

トラブルシューティング

MCP サーバーが認識されない

• settings.json のパスが正しいか確認
• Claude Code を再起動したか確認
• node /path/to/bin/smaregi-mcp.js を直接実行してエラーが出ないか確認

認証エラー (401)

• トークンキャッシュを削除: rm ~/.config/smaregi-mcp/tokens.json
• クライアント ID / シークレットが正しいか確認

スコープ不足 (403)

• Developer Platform でアプリのスコープ設定を確認
• スコープ変更後はトークンキャッシュを削除: rm ~/.config/smaregi-mcp/tokens.json

レート制限 (429)

環境	GET	POST/PUT/PATCH/DELETE
サンドボックス	10 回/秒	4 回/秒
本番	50 回/秒	20 回/秒

Retry-After ヘッダーの秒数だけ待ってから再試行してください。

ライセンス

MIT