Raley
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Raley Find organic spinach with the best unit price"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | bashThis 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 loginManual 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 loginCLI
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 balanceMCP 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 |
| Find products with unit pricing and value analysis |
| Add items to cart (returns product name for confirmation) |
| Remove items by SKU |
| View cart (supports |
| List, clip all, or sync coupons to local DB |
| Parse freeform grocery lists, find best matches (does not auto-add) |
| Check price history from local tracking DB |
| Order history with date range and spend totals |
| 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 persistenceHow 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 |
|
Price history DB |
|
Saved results |
|
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.jsonFormat:
{
"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]"
pytestDisclaimer
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 toolsaddC
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).
searchC
Search products. Returns best match with SKU, price, unit pricing.
Inputs: q (required), diet, sale.
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
Scored across 18 tools
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.
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.
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).
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
Related MCP Connectors
Search live store shelves, verify delivery windows, and run instant AI agent checkouts.
AI meal plans that fill your Kroger/Instacart cart - pantry-aware lists, all from chat.
AI-powered kitchen management — pantry, recipes, meal plans, shopping lists
Turn any shopping list into a ready-to-checkout grocery cart across 26 European supermarkets.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceIntegrates Kroger's public API with Claude to allow adding meal plan grocery lists directly to your Kroger cart via natural language.-
- AlicenseBqualityBmaintenanceEnables Claude to automate grocery shopping on Blinkit, including product search, cart management, location setup, and payment via UPI.1554MIT
- FlicenseAqualityDmaintenanceEnables logging and analyzing grocery purchases, tracking prices, spending patterns, and purchase history through natural language with Claude Desktop.5-
- FlicenseNot gradedqualityDmaintenanceEnables shopping at Tiv Taam grocery store through Claude, including recipe parsing and cart population.-