magento-mcp

MCP サーバー。Magento 2 ストアを AI アシスタントに公開します。手段は以下のとおりです。

• REST Admin API — カタログ、注文、顧客、CMS、在庫、プロモーション、ストア設定 (書き込みツールには confirm: true が必要)。Magento Integration に対する OAuth 1.0a で認証

• GraphQL — ストアフロント向けのカタログ検索、商品詳細、カテゴリツリー

• 直接の読み取り専用 SQL — run_readonly_sql ツールと、ライブの Magento データベースに対する組み込みインサイトクエリ。オプションで SSH トンネル経由でアクセス可能

ツール

また、1つの MCP リソースを公開します: magento://store/config (ストア設定 — 通貨、ロケール、ストアビュー、ベース URL)。

Related MCP server: Shopify MCP

セットアップ

1. npm install

2. .env.example を .env にコピーして、以下を記入します:

   • MAGENTO_BASE_URL と、Magento Integration (システム → 拡張機能 → 統合 → 新しい統合を追加) から取得した OAuth 1.0a 資格情報: MAGENTO_CONSUMER_KEY、MAGENTO_CONSUMER_SECRET、MAGENTO_ACCESS_TOKEN、MAGENTO_ACCESS_TOKEN_SECRET。このサーバーが実際に必要とする API リソースのみを Integration に付与してください — Magento はこれらの4つの値を、アクティベート時に一度だけ表示します。これにより、管理者ユーザーのパスワード認証をブロックする2FA制限を回避でき、しかも最小権限のアプローチです。

   • MAGENTO_DB_* — SELECT のみの権限を持つ MySQL ユーザーを指す必要があります:

     CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'change_me';
     GRANT SELECT ON magento_db.* TO 'mcp_readonly'@'%';
     FLUSH PRIVILEGES;

     いかなる状況でもこのユーザーに INSERT/UPDATE/DELETE/DDL を付与しないでください。アプリケーションレベルのクエリガード (src/db/guard.ts) は多層防御であり、安全境界ではありません。

3. npm run build

4. npm run test:connections — サーバーをアシスタントに接続する前に、.env の値に対して REST 認証、GraphQL、DB 接続を sanity-check します。TLS で失敗する場合は、下記の自己署名証明書を使ったローカル開発を参照してください。

5. Claude Desktop/Code に登録します。例: claude_desktop_config.json 内:

   {
     "mcpServers": {
       "magento": {
         "command": "node",
         "args": ["/var/www/html/magentoMCP/dist/index.js"],
         "env": {
           "MAGENTO_BASE_URL": "...",
           "MAGENTO_CONSUMER_KEY": "...",
           "MAGENTO_CONSUMER_SECRET": "...",
           "MAGENTO_ACCESS_TOKEN": "...",
           "MAGENTO_ACCESS_TOKEN_SECRET": "...",
           "MAGENTO_DB_HOST": "...",
           "MAGENTO_DB_NAME": "...",
           "MAGENTO_DB_READONLY_USER": "...",
           "MAGENTO_DB_READONLY_PASSWORD": "...",
           "MAGENTO_DB_SSH_HOST": "...",
           "MAGENTO_DB_SSH_USER": "...",
           "MAGENTO_DB_SSH_PRIVATE_KEY_PATH": "..."
         }
       }
     }
   }

   MAGENTO_DB_SSH_* フィールドは、DB 接続を SSH 経由でトンネリングする場合にのみ必要です。従来どおり直接接続するには、空白にするのではなく完全に省略してください。下記の「リモート/ファイアウォール内 DB への接続」を参照してください。

開発

• npm run dev — tsx 経由で TS ソースから直接実行

• npm run typecheck

• npm test — ユニットテスト (src/db/guard.test.ts は SQL 安全ガードレールをカバー)

• npm run test:connections — .env に対する REST/GraphQL/DB 到達可能性のライブスモークテスト (npm test の代わりにはなりません)

• npx @modelcontextprotocol/inspector node dist/index.js — ツールを対話的に一覧表示/呼び出し

自己署名証明書を使ったローカル開発 (mkcert、Warden など)

Node の fetch は、システムのトラストストアとは別に、Node 自身にバンドルされた CA リストを使用します。そのため、curl やブラウザがローカル発行の mkcert 証明書を信頼していても、Node は UNABLE_TO_VERIFY_LEAF_SIGNATURE で拒否します。Node に同じルート CA を指定してください:

NODE_EXTRA_CA_CERTS=$(mkcert -CAROOT)/rootCA.pem npm run dev

または、MCP クライアントがサーバーを起動する環境で NODE_EXTRA_CA_CERTS を設定します (例: claude_desktop_config.json の env ブロック)。また、MAGENTO_BASE_URL が証明書がカバーするホスト名と実際に一致していることを再確認してください (ERR_TLS_CERT_ALTNAME_INVALID は一致していないことを意味します)。ローカルの Magento セットアップでは、複数の *.local/*.example.com ホスト名が設定されていて、一致する証明書を持つのは1つだけということがよくあります。

リモート/ファイアウォール内 DB への接続 (SSH トンネル)

MAGENTO_DB_HOST/PORT はこのサーバーと同じマシン上にある必要はありません。mysql2 は TCP で接続するだけです。ただし、そのために MySQL のポートをインターネットに公開しないでください。DB がプライベートネットワーク/VPN 経由でまだ到達できない場合は、.env で MAGENTO_DB_SSH_* を設定して (完全なフィールド一覧は .env.example を参照)、代わりに SSH 経由で DB 接続をトンネリングしてください。このサーバーは SSH 接続を自ら開き (ssh2 パッケージ経由。シェルアウトした ssh プロセスではありません)、SSH ホスト側から解決された MAGENTO_DB_HOST/PORT にローカルポートを転送します。パスワードよりも秘密鍵 (MAGENTO_DB_SSH_PRIVATE_KEY_PATH) が推奨されます。従来どおり直接接続するには MAGENTO_DB_SSH_HOST を未設定のままにしてください。トンネルはオプトインであり、その変数が存在する場合にのみ有効になります。

安全上の注意

• 破壊的な REST ツール (update_product、delete_product、cancel_order、refund_order、update_customer、delete_customer、update_stock_item、set_config_value) はすべて、アクションをプレビューし、confirm: true を指定して呼び出されない限り何も実行しません。

• run_readonly_sql は単一の SELECT ステートメントのみを受け付け、DML/DDL キーワードと機密テーブル (admin_user など) を拒否し、LIMIT を注入/上限設定します — src/db/guard.ts を参照してください。これは DB ユーザーの SELECT のみの権限に加えてのものであり、その代わりではありません。

• クエリのタイムアウトと行数の上限は、.env の MAGENTO_DB_QUERY_TIMEOUT_MS / MAGENTO_DB_MAX_ROWS で設定できます。