MCP 服务器

smaregi-mcp

Enables interaction with the Smaregi POS API to manage products, sales, inventory, and member information directly through Claude Code. It provides a suite of CRUD tools and comprehensive API documentation to streamline retail management via natural language.

README

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      # トラブルシューティング

スマレジアプリの作成

developers.smaregi.dev でアプリを新規登録（種別: Web アプリ）
必要なスコープを有効化:
- 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
クライアント ID / シークレットを控える