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.

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