king-soopers-mcp
# king-soopers-mcp
A local [Model Context Protocol](https://modelcontextprotocol.io) server for shopping at King Soopers through the official [Kroger Developer API](https://developer.kroger.com). 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](docs/BUILD_SPEC.md) for the full specification and [docs/research/](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](https://docs.astral.sh/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
TDQS
Scored across 6 tools
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.
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.
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.
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.