Grocery MCP

A dedicated MCP and REST service that searches grocery retailers directly and returns reviewable product links. It starts with:

• Kettle Range Meat Co. — Milwaukee and Elm Grove

• Outpost Natural Foods — Capitol Drive, State Street, Bay View, and Mequon

start_grocery_checkout starts a cart the shopper pays for on the store site. Kettle Range returns the store checkout link. Outpost returns one https link that opens the cart this server already filled. This service does not take a card number or store retailer passwords.

A Kettle Range checkout link opens that guest cart on the store site. An Outpost checkout link opens the filled guest cart. The shopper pays on that page.

A printed menu starts as JSON the caller writes. build_shopping_list sums the ingredients, start_grocery_checkout fills the cart, and render_menu_pdf returns the landscape PDF in the tool result. The "Open the filled cart" link and QR code use that checkout URL. The file is not stored.

Connect

Hosted server:

https://grocery-mcp-production.up.railway.app/mcp

Claude and ChatGPT sign the person in. There is no shared password.

• Add Grocery in Claude

• ChatGPT, on a Business, Enterprise, or Edu workspace: open chatgpt.com/plugins, choose Add custom MCP server, paste the URL, and use OAuth.

Start with find_grocery_retailers, then search or hand off a list. For an order, call start_grocery_checkout. Product-link handoffs still need the shopper to open browser_session.start_url and then each product link in that same browser. cart_prefilled stays false on those handoffs.

Prices and stock come from the store's public site at the moment of the search. Kettle Range covers Milwaukee and Elm Grove. Outpost covers Capitol Drive, State Street, Bay View, and Mequon.

Related MCP server: Walmart MCP Server

Setup

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Run

python -m grocery_mcp.server
python -m grocery_mcp.server --http

HTTP endpoints:

• MCP: http://localhost:8080/mcp

• Health: http://localhost:8080/health

• OpenAPI: http://localhost:8080/docs

• Retailers: http://localhost:8080/v1/retailers

• Product search: http://localhost:8080/v1/products/search

• Handoffs: POST http://localhost:8080/v1/handoffs

When DATABASE_URL is configured, handoffs, Outpost cart plans, and OAuth dynamic client registrations are persisted in PostgreSQL. Without it, local development uses process memory.

MCP tools

• find_grocery_retailers

• search_grocery_products

• create_grocery_handoff

• start_grocery_checkout

• get_grocery_handoff

• create_grocery_order_template

• list_grocery_order_templates

• create_handoff_from_template

Example handoff input:

{
  "retailer": "kettle_range",
  "location_id": "milwaukee",
  "items": [
    {"name": "boneless chicken thighs", "quantity": 2, "unit": "lb"},
    {"name": "ground beef", "quantity": 1, "unit": "lb"}
  ]
}

Data behavior

Product names, prices, availability, and links come from each retailer's public customer storefront at request time. These storefront interfaces are not formal partner APIs and can change without notice. Responses include match confidence, alternatives, and observation timestamps so clients can make this uncertainty visible.

Matching requires strong token overlap, rejects obvious cross-category substitutions, and prefers available products. If no safe result exists, the item is explicitly unmatched rather than replaced with a loosely related item.

Reusable templates persist the retailer, location, and normalized grocery items. Running a template always performs fresh catalog searches and creates a new review-only handoff.

Directory listings

Registry name: io.github.AndrewVG23/grocery-mcp.

Server card: https://grocery-mcp-production.up.railway.app/.well-known/mcp/server-card.json

Tests

ruff check .
pytest