Skip to main content
Glama
Sign In
king-soopers-mcp

king-soopers-mcp

by Druhayes
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

king-soopers-mcp

A local Model Context Protocol server for shopping at King Soopers through the official Kroger Developer API. It lets an LLM client such as Claude Code or Claude Desktop find stores, search products with live store pricing, build a shopping list, and push it to your King Soopers cart. Checkout happens in the King Soopers app.

Status: design phase. See docs/BUILD_SPEC.md for the full specification and docs/research/ for the API and SDK research behind it.

What it can and cannot do

The Kroger Public API allows product and store lookup and adding items to a cart. It does not expose cart contents, item removal, checkout, or order history; those require a Kroger Partner agreement. This server keeps a local shadow cart so you can review a list before syncing it to Kroger.

Related MCP server: mcp-kroger

Stack

  • Python 3.12+, managed with uv

  • Official mcp Python SDK 2.x

  • httpx, pydantic-settings

  • OAuth2 via the Kroger developer API only; no scraping or password login

Setup (once implemented)

  1. Register an app at developer.kroger.com with redirect URI http://localhost:8000/callback.

  2. Copy .env.example to .env and fill in the client id and secret.

  3. uv sync

  4. Register with Claude Code:

claude mcp add --scope user --transport stdio king-soopers -- uv run --directory /path/to/king-soopers-mcp king-soopers-mcp

Privacy

Credentials and tokens stay on your machine in .env and a 0600 token file. The server only writes to your Kroger account when you explicitly call the cart sync tool.

License

MIT

Available Tools

6 tools
auth_statusA

Report whether Kroger credentials and tokens are usable.

Only expiry metadata is returned; token values are never exposed.

Inputs: no named parameters. Returns: Result of ``auth_status``.

find_storesA

Find King Soopers stores near a zip code.

Results are ordered by the API's own proximity ranking. Each store carries a search_scope string describing this search, for example 'within 10 mi of 80202'; the Kroger locations endpoint returns no per-store distance and no coordinates for the search centre, so no distance is reported per store.

Args: zip_code: 5-digit zip to search around. Falls back to KROGER_DEFAULT_ZIP. radius_miles: Search radius, 1-100 miles. limit: Maximum number of stores to return, 1-200.

Inputs: limit, zip_code, radius_miles. Returns: result

get_default_storeA

Show the store currently used for product prices and availability.

Inputs: no named parameters. Returns: Result of ``get_default_store`` / ``set_default_store``.

get_productA

Get one product with every image perspective and full fulfillment detail.

Args: product_id: The product_id or UPC from search_products. location_id: Store to price against. Defaults to the saved default store.

Inputs: product_id (required), location_id. Returns: A single product with all image perspectives and full fulfillment detail.

search_productsA

Search products with live pricing and stock at one King Soopers store.

Args: term: What to search for, for example 'whole milk'. location_id: Store to price against. Defaults to the saved default store. limit: Maximum number of products to return, 1-50. fulfillment: Optional filter: pickup, delivery, in_store, or ship_to_home.

Inputs: term (required), limit, fulfillment, location_id. Returns: result

set_default_storeA

Remember a store for later product searches.

Args: location_id: The location_id from find_stores, for example '62000115'.

Inputs: location_id (required). Returns: Result of ``get_default_store`` / ``set_default_store``.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: store search, default store state management, product search, product detail, and auth status. There is no meaningful overlap between search_products and get_product because one returns a list of matches while the other retrieves a single product by ID.

    Naming Consistency4/5

    Tool names mostly follow a clean verb_noun snake_case pattern like find_stores, set_default_store, search_products, and get_product. The only minor deviation is auth_status, which is a noun phrase rather than a verb_noun form, but it is still short and clearly readable.

    Tool Count5/5

    Six tools is a well-scoped size for a grocery store/product lookup MCP server. Each tool covers a necessary part of the workflow without redundancy or bloat.

    Completeness4/5

    The core workflow of finding a store, setting it as default, searching products, and retrieving product details is well covered. Minor gaps exist, such as no way to clear the default store or browse product categories, but these are workable and don't block the primary use case.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers