🛒 Kroger MCP サーバー 🛍️ -- Kroger ショッピング向け FastMCP

FastMCPサーバーは、クロードのようなAIアシスタントに、モデルコンテキストプロトコル（ MCP ）を介してクローガーの食料品ショッピング機能へのシームレスなアクセスを提供します。このサーバーにより、AIアシスタントは店舗の検索、商品の検索、ショッピングカートの管理、そしてkroger-api Pythonライブラリを介してクローガーの包括的な食料品データへのアクセスが可能になります。

📺 デモ

この MCP サーバーで Claude を使用して、店舗を検索し、製品を見つけ、アイテムをカートに追加します。

Related MCP server: mcp-carrefour

🚀 クイックスタート

前提条件

Kroger API認証情報（ Kroger Developer Portalから無料で入手可能）が必要です。Kroger Developer Portalにアクセスして、以下の操作を行ってください。

1. 開発者アカウントを作成する

2. アプリケーションを登録する

3. CLIENT_ID 、 CLIENT_SECRETを取得し、 REDIRECT_URIを設定します。

ユーザー認証を必要とするツールを初めて実行する際、ウェブブラウザでアプリの認証を求めるメッセージが表示されます。認証は、第三者ではなく、ご自身の登録済みアプリに対して行われます。

インストール

オプション 1: Claude Desktop で uvx を使用する (推奨)

PyPI に公開したら、リポジトリをクローンせずに uvx を使用してパッケージを直接実行できます。

Claude Desktop の設定ファイルを編集します。

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

Linux : ~/.config/Claude/claude_desktop_config.json

Windows : %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "kroger": {
      "command": "uvx",
      "args": [
        "kroger-mcp"
      ],
      "env": {
        "KROGER_CLIENT_ID": "your_client_id",
        "KROGER_CLIENT_SECRET": "your_client_secret", 
        "KROGER_REDIRECT_URI": "http://localhost:8000/callback",
        "KROGER_USER_ZIP_CODE": "10001"
      }
    }
  }
}

この方法の利点:

• 必要に応じてPyPIからパッケージを自動的にインストールします

• サーバーを実行するための隔離された環境を作成します

• 最新バージョンを簡単に入手できるようになります

• ローカルリポジトリのクローンを維持する必要がない

オプション2: ローカルクローンでUVを使用する

まず、ローカルにクローンを作成します。

git clone https://github.com/CupOfOwls/kroger-mcp

次に、Claude Desktop の構成ファイルを編集します。

{
  "mcpServers": {
    "kroger": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/cloned/kroger-mcp",
        "run",
        "kroger-mcp"
      ],
      "env": {
        "KROGER_CLIENT_ID": "your_client_id",
        "KROGER_CLIENT_SECRET": "your_client_secret", 
        "KROGER_REDIRECT_URI": "http://localhost:8000/callback",
        "KROGER_USER_ZIP_CODE": "10001"
      }
    }
  }
}

オプション3: PyPIからインストールする

# Install with uv (recommended)
uv pip install kroger-mcp

# Or install with pip
pip install kroger-mcp

オプション4: ソースからインストールする

# Clone the repository
git clone https://github.com/CupOfOwls/kroger-mcp
cd kroger-mcp

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

構成

プロジェクト ルートに.envファイルを作成するか、JSON 構成を介して env 値を渡します。

# Required: Your Kroger API credentials
KROGER_CLIENT_ID=your_client_id_here
KROGER_CLIENT_SECRET=your_client_secret_here
KROGER_REDIRECT_URI=http://localhost:8000/callback

# Optional: Default zip code for location searches
KROGER_USER_ZIP_CODE=90274

サーバーの実行

# With uv (recommended)
uv run kroger-mcp

# With uvx (directly from PyPI without installation)
uvx kroger-mcp

# Or with Python directly
python server.py

# With FastMCP CLI for development
fastmcp dev server.py --with-editable .

🛠️ 機能

💬 組み込みの MCP プロンプト

• ショッピングパス: 食料品リストに基づいて店内の最適な経路を見つける

• 薬局チェック：希望する場所の薬局が営業しているか確認する

• 店舗選択: ユーザーが好みの Kroger 店舗を設定できるように支援します

• レシピショッピング：レシピを見つけて材料をカートに追加します

📚 利用可能なツール

位置情報ツール

製品ツール

カートツール

情報ツール

プロフィールツール

ユーティリティツール

🧰 ローカル限定のカート追跡

Kroger API はカートの表示機能を提供しないため、このサーバーはローカル トラッキングを維持します。

ローカルカートストレージ

• ファイル: kroger_cart.json

• 内容: タイムスタンプ付きの現在のカートアイテム

• 自動: 自動的に作成および更新されます

注文履歴

• ファイル: kroger_order_history.json

• 内容: 発注タイムスタンプ付きの過去の注文

• 使用方法: mark_order_placedで完了したカートを履歴に移動する

🚧 Kroger パブリック API の制限

• 表示のみ: remove_from_cartおよびclear_current_cartツールはローカルトラッキングにのみ影響し、実際のKrogerカートには影響しません。

• ローカル同期: ユーザーが Kroger アプリ/ウェブサイトでカートからアイテムを削除した場合にのみ、これらのツールを使用します。

• 一方通行：パブリックAPIでは、Krogerのカートに商品を追加することはできますが、削除することはできません。パートナーAPIではこれらの操作が可能ですが、Krogerとの契約が必要です。

**注:**レート制限はオペレーションごとではなくエンドポイントごとに適用されます。必要に応じて、同じエンドポイントを使用して複数のオペレーションに呼び出しを分散できます。

🏫 基本的なワークフロー

1. 優先場所を設定します:

   User: "Find Kroger stores near 90274"
   Assistant: [Uses search_locations tool]
   User: "Set the first one as my preferred location"
   Assistant: [Uses set_preferred_location tool]

2. 製品の検索と追加:

   User: "Add milk to my cart"
   Assistant: [Uses search_products, then add_items_to_cart]
   
   User: "Add bread, eggs, and cheese to my cart"
   Assistant: [Uses search_products for each, then bulk_add_to_cart]

3. カートと注文の管理:

   User: "What's in my cart?"
   Assistant: [Uses view_current_cart tool to see local memory]
   
   User: "I placed the order on the Kroger website"
   Assistant: [Uses mark_order_placed tool, moving current cart to the order history]

🤝 貢献する

貢献を歓迎します！お気軽にプルリクエストを送信してください。大きな変更については、まずIssueを開いて、変更したい点について議論してください。

📄 ライセンス

このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細についてはLICENSEファイルを参照してください。

⚠️免責事項

これはKrogerパブリックAPIの非公式MCPサーバーです。Krogerと提携、承認、またはスポンサー契約を結んでいません。

Kroger API に関する質問については、 Kroger 開発者ポータルにアクセスするか、 kroger-apiパッケージのドキュメントをお読みください。