Freento Mcp Server

Freento MCP for Magento 2 — ユーザーガイド

Model Context Protocol（MCP）を使用して、Magento 2 ストアを Claude や ChatGPT などの AI アシスタントに接続します。

目次

• 概要
• 要件
• インストール
• 設定
  • Claude Code
  • Claude Desktop
  • ChatGPT
• 利用可能なツール
• 使用例
• フィルタリングと演算子
• 集計と分析
• トラブルシューティング
• セキュリティ

概要

Freento MCP は、AI アシスタントを外部データソースに接続するためのオープン標準である Model Context Protocol を実装した Magento 2 拡張機能です。この拡張機能を使用すると、次のことができます。

• 自然言語を使って注文、商品、顧客、在庫を照会する
• 売上レポートや分析をその場で作成する
• システムの健全性（PHP、MySQL、キャッシュ、検索エンジンのバージョン）を監視する
• 管理ユーザーとセキュリティ設定を監査する

仕組み：

┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
│  AI Assistant   │  HTTP   │  Freento MCP    │         │   Magento 2 /   │
│  (Claude/GPT)   │ ◄─────► │  Server         │ ◄─────► │Server Resources │
└─────────────────┘ JSON-RPC└─────────────────┘         └─────────────────┘

MCP サーバーは、AI アシスタントと Magento のインストール環境の間をつなぐ安全なブリッジとして機能し、データベース、設定、その他の Magento サブシステムなど、さまざまなストアのリソースへのアクセスを提供します。

要件

• Magento 2.4.x（Open Source または Commerce）
• PHP 8.1 以降
• MCP 対応の AI クライアント（Claude Code、Claude Desktop、または MCP プラグインを備えた ChatGPT）

インストール

Composer 経由（推奨）

composer require freento/module-mcp
php bin/magento module:enable Freento_Mcp
php bin/magento setup:upgrade
php bin/magento cache:flush

手動インストール

1. モジュールをダウンロードし、app/code/Freento/Mcp/ に展開します
2. モジュールを有効化します。

php bin/magento module:enable Freento_Mcp
php bin/magento setup:upgrade
php bin/magento cache:flush

インストールの確認

php bin/magento module:status Freento_Mcp

期待される出力：Module is enabled

設定

手順 1：ACL ロールを作成する

1. Magento Admin で、System > Freento MCP > ACL Rules に移動します
2. Add New Role をクリックします
3. 名前（例：「AI アシスタント」）を入力します
4. ロールでアクセスできるツールを選択します。
   • 販売ツール（注文、見積もり、クレジットメモ）
   • カタログツール（商品、在庫）
   • 顧客ツール
   • 管理ツール
   • システムツール
5. ロールを保存します

手順 2：OAuth クライアントを作成する

1. System > Freento MCP > AI MCP Clients に移動します
2. Add New Client をクリックします
3. 名前（例：「Claude Code」）を入力します
4. 手順 1 で作成した ACL ロールを選択します
5. クライアントを保存します
6. Client ID と Client Secret をコピーします

手順 3：アクセストークンを生成する

1. 作成した OAuth クライアントを開きます
2. Generate OTP をクリックし、ワンタイムパスワードをコピーします（有効期間は 24 時間です）
3. Generate Token をクリックし、プロンプトが表示されたら OTP を入力します
4. 生成された Access Token をコピーします

Claude Code

プロジェクトの .mcp.json に追加します。

{
  "mcpServers": {
    "magento": {
      "type": "http",
      "url": "https://your-store.com/freento_mcp/index/index",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

その後、Claude Code で MCP に再接続します。

/mcp

Claude Desktop

Claude Desktop の設定ファイル（Linux/Mac では ~/.config/claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json）を編集します。

{
  "mcpServers": {
    "magento": {
      "type": "http",
      "url": "https://your-store.com/freento_mcp/index/index",
      "headers": {
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    }
  }
}

変更を適用するには、Claude Desktop を再起動します。

ChatGPT およびその他の Web クライアント

OAuth 2.0 に対応した Web ベースの AI ツールの場合：

1. ストアの MCP エンドポイントを登録します：https://your-store.com/freento_mcp/index/index
2. 手順 2 で取得した Client ID と Client Secret を入力します
3. 認証を求められたら、OAuth クライアントのページで生成した OTP を入力します
4. OAuth 認証フローを完了します

利用可能なツール

各ツールは柔軟なフィルタリング、並べ替え、ページネーションに対応しています。AI と組み合わせることで、これらの機能を実質的に無制限に活用できます。AI は複数のクエリを実行し、データを相互参照し、結果をグループ化して集計し、インテリジェントな分析を提供できます。

AI でできること：

• 1 回の会話で異なるエンティティに対して複数のクエリを実行する
• 演算子 eq、neq、in、like、gt、gte、lt、lte を使って任意のフィールドで絞り込む
• 結果を並べ替え、ページネーションする
• sum、count、avg、min、max で集計する
• フィールドまたは期間（日、月）でグループ化する
• 複数のソースのデータを組み合わせて分析する

販売ツール

ツール	説明
get_orders	フィルタリング、ページネーション、集計を使用して注文を照会します
get_order_items	注文明細（注文内の商品）を取得します
get_quotes	ショッピングカート（有効および放棄されたもの）を照会します
get_quote_items	カートの明細を取得します
get_creditmemos	クレジットメモを照会します

マーケティングツール

ツール	説明
get_cart_price_rules	カート価格ルールを照会します
get_coupons	クーポンを照会します

カタログツール

ツール	説明
get_products	属性フィルタリングを使用して商品を照会します
get_categories	商品カテゴリを照会します
get_product_prices	顧客グループとウェブサイトごとの商品価格を取得します
get_product_tier_prices	段階価格ルール（数量ベースの割引）を取得します
get_tax_rules	税ルールと税率を取得します
get_stock_single_stock	在庫数を取得します

顧客ツール

ツール	説明
get_customers	顧客アカウントを照会します

管理ツール

ツール	説明
get_admins	管理者ユーザーとそのロールを一覧表示します
get_locked_admins	ログイン失敗によりロックされた管理者アカウントを検索します

システムツール

ツール	説明
get_system_versions	Magento、PHP、MySQL、Redis、OpenSearch のバージョンを取得します
get_stores	ストア階層（ウェブサイト、ストアグループ、ストアビュー）を取得します

使用例

設定が完了したら、AI アシスタントに自然言語で質問できます。

注文と販売

"How many orders were placed last month?"
"Show me the 10 most recent orders"
"Find all orders over $500 that are still processing"
"What's the total revenue by payment method this year?"
"List orders for customer [email protected]"

商品と在庫

"Show me out of stock products"
"Find products with SKU starting with 'ABC'"
"List products with less than 10 items in stock"
"Get all configurable products updated this week"

顧客

"How many customers registered this month?"
"Find customer with email [email protected]"
"List customers in the Wholesale group"

システムと管理

"What PHP version is running?"
"Show me all admin users"
"Are there any locked admin accounts?"
"What search engine is configured?"

分析とレポート

"Revenue by month for the last 12 months"
"Top 10 customers by total order value"
"Average order value by payment method"
"Order count by status"

AI を活用した高度な分析

データと AI の推論を組み合わせることで、その真価が発揮されます。複雑なビジネス上の質問をして、実行可能なインサイトを得ましょう。

顧客インテリジェンス：

"Analyze my top 10 customers from the last 6 months. Who are they,
what do they buy, and how can I increase sales?"

AI はデータを取得し、次のような分析を提供します。

Mike Johnson — 合計 $4,250、8 件の注文 プロフィール：シンバルとドラムスティックを 5～6 週間ごとに購入するプロのドラマー

推奨事項：ドラムスティックの自動補充を設定し、新しいシンバルの入荷情報を先行案内して、「ドラマー向けロイヤルティ」割引ランクを検討します。

解約防止：

"Find customers who were active but haven't ordered in 90 days.
What patterns do you see and how can I win them back?"

在庫の最適化：

"Analyze sales velocity vs current stock levels.
What should I reorder and what's at risk of becoming dead stock?"

収益機会：

"What patterns exist in high-value orders? How can I get more customers
to spend at that level?"

放棄されたカートの分析：

"Look at abandoned carts from this week. What are people leaving behind
and what might be causing it?"

これにより、ストアのデータが戦略的なビジネスインテリジェンスへと変わります。通常なら、スプレッドシートを使って何時間も作業するか、専任のアナリストに依頼しなければ得られないインサイトです。

フィルターと演算子

すべてのリストツールは、filters パラメーターによる高度なフィルタリングに対応しています。

フィルターの構造

{
  "filters": {
    "field_name": { "operator": "value" }
  }
}

使用可能な演算子

演算子	説明	例
eq	等しい	{"status": {"eq": "processing"}}
neq	等しくない	{"status": {"neq": "canceled"}}
in	リスト内にある	{"status": {"in": ["processing", "complete"]}}
nin	リスト内にない	{"status": {"nin": ["canceled", "closed"]}}
like	SQL LIKE パターン	{"email": {"like": "%@gmail.com"}}
nlike	SQL NOT LIKE	{"sku": {"nlike": "TEST%"}}
gt	より大きい	{"grand_total": {"gt": 100}}
gte	以上	{"qty": {"gte": 10}}
lt	より小さい	{"created_at": {"lt": "2024-01-01"}}
lte	以下	{"price": {"lte": 50}}

フィルターの組み合わせ

複数のフィルターは AND ロジックで組み合わされます。

{
  "filters": {
    "status": {"in": ["processing", "pending"]},
    "grand_total": {"gte": 100},
    "created_at": {"gte": "2024-01-01"}
  }
}

日付のフィルタリング

YYYY-MM-DD または YYYY-MM-DD HH:MM:SS 形式を使用します。

{
  "filters": {
    "created_at": {"gte": "2024-01-01", "lt": "2024-02-01"}
  }
}

集計と分析

get_orders ツールは分析用の集計に対応しています。

パラメーター

パラメーター	値	説明
function	count, sum, avg, min, max	集計関数
field	grand_total, total_qty_ordered, total_item_count	集計するフィールド
group_by	status, month, day, customer_email, store_id, payment_method	グループ化

例

注文数の合計：

{"function": "count"}

月別売上：

{
  "function": "sum",
  "field": "grand_total",
  "group_by": "month"
}

支払い方法別の平均注文額：

{
  "function": "avg",
  "field": "grand_total",
  "group_by": "payment_method"
}

支出額上位10名の顧客：

{
  "function": "sum",
  "field": "grand_total",
  "group_by": "customer_email",
  "filters": {
    "status": {"nin": ["canceled", "closed"]}
  },
  "limit": 10
}

トラブルシューティング

AI アシスタントにツールが表示されない

1. モジュールが有効になっていることを確認します：

   php bin/magento module:status Freento_Mcp
   

2. Magento のキャッシュをフラッシュします：

   php bin/magento cache:flush
   

3. AI クライアントで MCP に再接続します（例：Claude Code では /mcp）

「Authentication failed」エラー

• アクセストークンが正しいことを確認します
• Magento Admin で OAuth Client が有効になっていることを確認します
• トークンの有効期限が切れている場合は、再生成します

「Access denied」エラー

ACL Role に必要な権限がありません。System > Freento MCP > ACL Rules で ACL Role を編集し、必要なツールへのアクセスを許可してください。

接続タイムアウト

• Magento ストアにインターネット経由でアクセスできることを確認します
• ファイアウォールのルールで受信接続が許可されていることを確認します
• ローカル開発では、ngrok などのトンネルサービスを使用します

エンドポイントを手動でテストする

curl -X POST https://your-store.com/freento_mcp/index/index \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

セキュリティ

ベストプラクティス

1. HTTPS を使用する — 本番環境では、API 通信を暗号化するために必ず HTTPS を使用してください

2. 最小限の権限 — ACL Roles を通じて、用途に必要なツールのみを許可してください

3. クライアントを分ける — ユーザーや用途ごとに OAuth Clients を個別に作成してください

4. 定期的な監査 — 有効なクライアントを定期的に確認し、使用していないものは無効にしてください

5. トークンのローテーション — アクセストークンを定期的に再生成してください

6. 匿名化モード — Stores > Configuration > Freento MCP > Privacy で匿名化モードを有効にすると、MCP ツールの応答から PII フィールド（メールアドレス、名前）が隠されます。MCP 経由で接続する AI アシスタントはサードパーティーサービスであるため、顧客の個人データを外部に送信しないよう、明示的に必要な場合を除き、このモードを有効にすることをおすすめします。

トークンのセキュリティ

• トークンをバージョン管理にコミットしないでください
• 環境変数または安全なシークレット管理を使用してください
• トークンを定期的にローテーションしてください
• 漏えいした場合は、ただちにトークンを取り消してください

サポート

お問い合わせ： https://freento.com/contact

ライセンス

MIT ライセンス — 詳細は LICENSE を参照してください。