Skip to main content
Glama

Raley

Named after someone who made grocery day feel less like a hostage negotiation with your own pantry.

Automated grocery shopping assistant with intelligent unit pricing, automatic coupon clipping, and an MCP server so your AI can argue with produce departments on your behalf.

What This Does

You tell Raley what you need. Raley finds the best deal, calculates unit pricing across every bizarre measurement the grocery industry has invented (per oz, per lb, per "each" — what even is an "each"), clips relevant coupons, and manages your cart. All through a CLI or Claude Desktop.

The grocery store API uses F5 bot detection, so Raley shells out to curl for TLS fingerprint evasion instead of using Python HTTP libraries that get immediately flagged. Yes, we're using subprocess.run(["curl", ...]) in 2026. Sometimes the unglamorous solution is the one that actually works.

Related MCP server: blinkit-mcp

Install

curl -fsSL https://raw.githubusercontent.com/johnzfitch/raley-bot/main/install.sh | bash

This clones the repo, sets up a Python venv, installs dependencies, and symlinks raley-bot to ~/.local/bin. Requires git and curl (installs uv automatically if missing).

Then log in:

raley-bot login

Manual Install

git clone https://github.com/johnzfitch/raley-bot.git
cd raley-bot

uv venv && source .venv/bin/activate
uv pip install -e ".[login]"

raley-bot login

CLI

raley search "organic spinach"    # Find products with unit pricing
raley history                     # Previously purchased items
raley offers                      # Available coupons
raley clip-all                    # Clip everything. All of it.
raley status                      # Session health check
raley orders                      # Order history
raley points                      # Something Extra balance

MCP Server (Claude Desktop / Claude Code)

Claude Desktop — add to ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "raley-bot": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/raley-bot", "raley-mcp"]
    }
  }
}

Claude Code — add to ~/.claude/settings.json:

{
  "mcpServers": {
    "raley-bot": {
      "command": "/path/to/raley-bot/.venv/bin/raley-mcp",
      "args": []
    }
  }
}

The install script configures these automatically.

Then talk to Claude like a normal person:

"Find me avocados, show me the best deal"
"Add organic spinach to my cart"
"What's in my cart?"
"Plan a grocery run: milk, eggs, bread, chicken thighs"

MCP Tools

Tool

What It Does

search

Find products with unit pricing and value analysis

add

Add items to cart (returns product name for confirmation)

remove

Remove items by SKU

cart

View cart (supports summary_only, save_to_file, limit)

offers

List, clip all, or sync coupons to local DB

plan

Parse freeform grocery lists, find best matches (does not auto-add)

price

Check price history from local tracking DB

orders

Order history with date range and spend totals

auth

Session status (no cookie values exposed)

Unit Pricing

Raley normalizes prices across every unit the grocery industry throws at you. A 6CT avocado bag at $4.99 becomes $0.83/unit. A 2lb chicken breast at $8.99 becomes $0.28/oz. Weight-based items show per-oz or per-lb depending on size. Liquids get per-ml. Count items get per-unit.

{
  "sku": "10101877",
  "name": "Hass Avocado, 6CT Bag",
  "price": "$4.99",
  "cents": 499,
  "per_unit": "$0.83"
}

Architecture

raley_assistant/
├── api.py           # Curl-based HTTP client (F5 evasion)
├── cli.py           # Click CLI with Rich tables
├── mcp_server.py    # MCP tools for Claude Desktop
├── unit_pricing.py  # Normalize $/oz, $/lb, $/unit, $/ml
├── cart_builder.py  # Freeform grocery list parsing
├── reasoning.py     # Purchase frequency analysis
├── db.py            # SQLite price history tracking
├── auth.py          # Browser-based login (Helium/Selenium)
└── cookies.py       # Session persistence

How the HTTP Client Works

The store's API sits behind F5 BIG-IP with browser fingerprinting. Python's requests and httpx get blocked because their TLS handshakes don't match real browsers. Rather than importing a Rust-based TLS emulation library (the previous approach using rnet, which created a phantom dependency that was never wired in), the client shells out to system curl which naturally produces a browser-like TLS fingerprint. Ugly, effective, zero exotic dependencies.

Data Storage

What

Where

Session cookies

~/.config/raley-assistant/cookies.json (mode 0600)

Price history DB

~/.local/share/raley-assistant/raley.db

Saved results

~/.local/share/raley-assistant/*.json (mode 0600)

Security Notes

Session cookies are written with 0600 permissions (owner read/write only). Cookie values are sanitized for header injection characters before being passed to curl. No credentials, tokens, or cookie values are ever logged, committed, or included in MCP tool responses. The auth tool explicitly returns session status without exposing cookie contents.

The search tool is read-only — it does not silently clip coupons or modify cart state. Write operations (add, remove, offers clip_all) are always explicit.

Rate limiting is applied to bulk operations (200ms between requests, 500ms every 10th request) to avoid triggering bot detection.

Preferences

Copy the example and edit to taste:

cp preferences.example.json ~/.config/raley-assistant/preferences.json

Format:

{
  "milk": {
    "brand": "Clover",
    "type": "whole",
    "size": "gallon"
  },
  "general": {
    "prefer_local": true,
    "organic_preference": "indifferent",
    "budget_target": 200
  }
}

Troubleshooting

Session expired? → raley-bot login

Browser login not working? → Export cookies manually with a browser extension ("Cookie-Editor" or "EditThisCookie"), save as JSON, then raley login --file cookies.json

Database corrupted? → rm ~/.local/share/raley-assistant/raley.db (rebuilds on next search)

Coupon clip limit? → Some manufacturer coupons have daily claim limits. This is server-side, not a bug.

Development

uv pip install -e ".[dev]"
pytest

Disclaimer

This is an unofficial tool not affiliated with or endorsed by the grocery chain. Use responsibly and in accordance with their Terms of Service. This project is named after a person, not a brand.

License

Unlicense

Available Tools

18 tools
addC

Add to cart. Need SKU and price_cents from search.

Inputs: sku (required), cents (required), qty.

add_planA

Bulk add items to cart. Pass comma-separated 'sku:cents' or 'sku:cents:qty' pairs.

Inputs: items (required).

authA

Check authentication status (no cookie values exposed).

Inputs: no named parameters.

cartB

View cart. Supports summary_only, save_to_file, and limit options.

Inputs: limit, save_to_file, summary_only.

cart_diffA

Compare a list of expected SKUs against the actual cart. Shows missing, extra, and quantity mismatches.

Inputs: expected_skus (required).

dealsA

Best-value items this week: clipped coupons + sale prices + price history. Run after 'offers sync'.

Inputs: limit, gi_filter.

favoritesC

Purchase history from 'previously purchased' API.

Inputs: type, limit.

knowledgeA

Search installed T1D reference books: GI tables, insulin math, carb counting, recipes, meal planning. Use when the user asks about nutrition science, insulin timing, or needs recipe ideas.

Inputs: q, book, limit, heading.

memoryB

Read or write shopping memory: T1D config, notes, preferences. Persists across sessions.

Inputs: action (required), key, limit, value, +1 more.

offersD

Coupons. action: list|clip_all|sync.

Inputs: cat, limit, action, save_to_file.

ordersD

Order history.

Inputs: days, limit, save_to_file, summary_only.

planC

Parse grocery list, find matches. Does not add to cart.

Inputs: items (required), budget, save_to_file, summary_only.

priceC

Price history by SKU, search local DB, or clear cache. Use clear=true when user changes store/delivery location.

Inputs: q, sku, clear.

read_savedA

Read a previously saved result file (from save_to_file=true). Returns the JSON contents.

Inputs: filename.

removeB

Remove from cart by SKU.

Inputs: sku (required).

search_batchA

Search multiple products at once. Returns best match per query. Use instead of calling search N times.

Inputs: queries (required).

storeB

View/change fulfillment store and delivery address. Prices and availability depend on the fulfillment store.

Inputs: action (required), address, address_id, store_number.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 18 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: search/add/remove/cart handle core shopping, while deals/offers, price, plan, orders, favorites, and knowledge cover different aspects. A few pairs overlap conceptually (search vs search_batch, add vs add_plan, deals vs offers), but descriptions clarify when to use each.

    Naming Consistency2/5

    Tool names mix single-word nouns (deals, cart, offers, store, memory, knowledge) with imperative verbs (search, add, remove, plan) and compound verb_noun forms (cart_diff, add_plan, search_batch). There is no consistent naming convention, which makes the set feel less predictable.

    Tool Count4/5

    With 18 tools, the server is on the heavier side but each tool addresses a specific need in the grocery shopping workflow. The count is justified given the breadth of features (product search, cart management, deals, price history, planning, memory, and account functions).

    Completeness4/5

    The tool surface covers core grocery tasks well: searching, adding/removing/viewing cart, bulk operations, deal retrieval, price history, order history, favorites, store selection, and user preferences. Minor gaps exist (e.g., no direct quantity update tool, no checkout/order placement), but they are workable and the domain is well represented.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers