Skip to content

kurozumi/eccube-mcp-server

BranchesTags

Repository files navigation

EC-CUBE MCP Server

EC-CUBE 4用のMCP（Model Context Protocol）サーバーです。 EC-CUBEのGraphQL APIを通じて、ClaudeなどのAIアシスタントから商品の検索・在庫確認・在庫更新ができるようになります。

必要要件

  • EC-CUBE 4.3以上
  • Web APIプラグイン（Api42）インストール済み
  • Node.js 18以上
  • Claude Desktop または Claude Code（どちらか一方）

クイックスタート

コマンド不要でセットアップ（初心者向け）

  1. 最新リリース からランチャーをダウンロード
    • Mac: launcher-mac.zip を展開して eccube-mcp-setup.command をダブルクリック
    • Windows: launcher-windows.zip を展開して eccube-mcp-setup.bat をダブルクリック
  2. ブラウザが自動で開きます。EC-CUBEのURLとアクセストークンを入力して「Claudeに登録する」ボタンを押すだけです
  3. Claudeを再起動すると利用できるようになります

Mac の注意: 初回起動時にセキュリティ警告が出る場合は、右クリック→「開く」を選択してください。

Node.js が必要です: ランチャーを起動するには Node.js 18以上 がインストールされている必要があります。未インストールの場合はアラートが表示されます。

コマンドラインからセットアップ

1. ダウンロード

リリースから配布パッケージを取得する場合:

  1. 最新リリース から eccube-mcp-server-vX.X.X.zip をダウンロードして展開
  2. 展開したディレクトリで以下を実行：
npm install --omit=dev  # 実行に必要な依存パッケージのみインストール
npm run setup

リポジトリをクローンする場合:

git clone https://github.com/kurozumi/eccube-mcp-server.git
cd eccube-mcp-server
npm install
npm run setup

2. EC-CUBEのアクセストークン取得方法

EC-CUBE管理画面で 設定 → API管理 → OAuth管理 からOAuthクライアントを登録し、アクセストークンを取得してください。

3. Claudeを再起動

登録後、Claude DesktopまたはClaude Codeを再起動するとEC-CUBEが利用できるようになります。

利用可能なツール

ツール 説明
search_products キーワード（商品名・商品コード）で商品を検索。価格・在庫情報も取得
check_stock 商品名または商品コードを指定して在庫数を確認
update_stock 商品規格コードを指定して在庫数を更新。在庫無制限の設定も可能
analyze_sales 指定期間の売上を日次・月次で集計。注文件数・売上合計・平均注文金額を取得
get_sales_ranking 指定期間の売れ筋商品を販売数量・売上金額でランキング表示

カスタムツール

~/.eccube-mcp/custom-tools.json にツール定義を記述するだけで、独自の集計ツールを MCP に追加できます。ファイルが存在しない場合はエラーなく通常起動します。

定義ファイル: ~/.eccube-mcp/custom-tools.json

{
  "tools": [
    {
      "name": "get_monthly_revenue",
      "description": "月別売上を集計",
      "query": "{ orders { id totalPrice } }",
      "inputSchema": {
        "type": "object",
        "properties": {
          "from": { "type": "string", "description": "開始日(YYYY-MM-DD)" },
          "to": { "type": "string", "description": "終了日(YYYY-MM-DD)" }
        },
        "required": ["from", "to"]
      }
    }
  ]
}

フィールド一覧:

フィールド 必須 説明
name Yes ツール名
description Yes ツールの説明。Claude がツールを選択する際に参照される
query Yes 実行する GraphQL クエリ
inputSchema No 入力パラメーターのスキーマ定義

inputSchema.properties の各フィールドには以下のキーを指定できます：

キー 説明
type 型（string、number など）
description Claude がパラメーターの意味を理解して適切な値を渡してくれる。具体的に書くほど精度が上がる

使用例

MCPサーバー名を指定して話しかける

Claudeは複数のMCPサーバーやツールを同時に持っていることがあります。サーバー名を指定しない場合、どのシステムへの操作か曖昧になりClaudeが確認を求めることがあります。設定時に登録したサーバー名（デフォルトは eccube）を会話の冒頭に含めると、迷わずEC-CUBEを操作してもらえます。

# 曖昧な例（どのシステムへの操作か不明なため確認が入ることがある）
「商品一覧を表示して」
「在庫を確認して」

# 明確な例（サーバー名 eccube を先頭に付ける）
「eccube の商品一覧を表示して」
「eccube で在庫が10個以下の商品を教えて」
「eccube の商品コードABC-001の在庫を50個に更新して」

「EC-CUBEで〜」と明示する方法も同様に有効です。

Claudeに以下のような指示ができます：

  • 「eccube で在庫が10個以下の商品を教えて」
  • 「eccube で〇〇という商品の在庫を確認して」
  • 「eccube の商品コードABC-001の在庫を50個に更新して」
  • 「eccube で△△を検索して価格と在庫を一覧で見せて」
  • 「eccube で先月の売上を月次で集計して」
  • 「eccube で今月の売れ筋商品トップ10を売上順で教えて」

複数のEC-CUBEを使い分ける

本番環境とステージング環境など、複数のEC-CUBEを登録して使い分けることができます。

登録方法

セットアップ画面の「サーバー名」に区別できる名前を入力して、それぞれ登録します。登録済みのサーバーはセットアップ画面上部に一覧表示されるので、名前を忘れても確認できます。

サーバー名 用途
eccube-production 本番環境
eccube-staging ステージング環境

Claudeへの指示方法

サーバー名をそのまま会話で伝えるだけで、Claudeが対応するEC-CUBEを使い分けます。

「eccube-staging の在庫を確認して」
→ ステージング環境のEC-CUBEに接続して在庫を確認

「eccube-production の商品コードABC-001の在庫を50個に更新して」
→ 本番環境のEC-CUBEに接続して在庫を更新

サーバー名を省略した場合は、Claudeが登録されているEC-CUBEを自動的に選択します。

環境変数

変数名 必須 説明
ECCUBE_API_URL Yes EC-CUBEサイトのURL（例: https://your-eccube-site.com）
ECCUBE_ACCESS_TOKEN Yes Web APIプラグインで発行したアクセストークン
ECCUBE_REFRESH_TOKEN No アクセストークン自動更新用のリフレッシュトークン
ECCUBE_CLIENT_ID No OAuth クライアントID
ECCUBE_CLIENT_SECRET No OAuth クライアントシークレット

ECCUBE_REFRESH_TOKEN・ECCUBE_CLIENT_ID・ECCUBE_CLIENT_SECRET の3つをすべて設定すると、アクセストークンの有効期限（1時間）が切れたときに自動でトークンを更新します。

手動設定（上級者向け）

GUIセットアップを使わずに手動で設定することもできます。

Claude Code

~/.claude.json を編集：

{
  "mcpServers": {
    "eccube": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/eccube-mcp-server/build/index.js"],
      "env": {
        "ECCUBE_API_URL": "https://your-eccube-site.com",
        "ECCUBE_ACCESS_TOKEN": "your-access-token",
        "ECCUBE_REFRESH_TOKEN": "your-refresh-token",
        "ECCUBE_CLIENT_ID": "your-client-id",
        "ECCUBE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "eccube": {
      "command": "node",
      "args": ["/path/to/eccube-mcp-server/build/index.js"],
      "env": {
        "ECCUBE_API_URL": "https://your-eccube-site.com",
        "ECCUBE_ACCESS_TOKEN": "your-access-token",
        "ECCUBE_REFRESH_TOKEN": "your-refresh-token",
        "ECCUBE_CLIENT_ID": "your-client-id",
        "ECCUBE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

リフレッシュトークンを使わない場合は ECCUBE_REFRESH_TOKEN・ECCUBE_CLIENT_ID・ECCUBE_CLIENT_SECRET の3行を省略できます。

注意事項

  • 在庫更新は即座にデータベースに反映され、取り消せません。 実行前に必ず内容を確認してください。
  • アクセストークンの有効期限は1時間です。リフレッシュトークンを設定すると自動更新されます。
  • 顧客・受注情報へのアクセスは個人情報保護の観点から実装していません。

HTTPS・自己署名証明書について

EC-CUBEをローカル環境でHTTPS（自己署名証明書）で運用している場合、Node.jsの fetch はデフォルトでTLSエラーになります。

推奨: 自己署名証明書を信頼させる

# 環境変数に証明書パスを設定する
NODE_EXTRA_CA_CERTS=/path/to/your/cert.pem node build/index.js

Claude Code の設定に追記する場合:

"env": {
  "ECCUBE_API_URL": "https://your-store.example.com",
  "ECCUBE_ACCESS_TOKEN": "your-access-token",
  "NODE_EXTRA_CA_CERTS": "/path/to/your/cert.pem"
}

注意: NODE_TLS_REJECT_UNAUTHORIZED=0 は TLS 検証を完全に無効化するため、中間者攻撃（MITM）のリスクがあります。本番環境では使用しないでください。

参考記事

関連リンク

License

GPL-2.0

Author

Akira Kurozumi info@a-zumi.net

https://a-zumi.net

About

MCP (Model Context Protocol) Server for EC-CUBE 4

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

v1.1.1 Latest
May 15, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages