bguillow-rgb/percolate-mcp

Query the Percolate specialty coffee database from Claude, or any MCP-compatible AI client. Read-only access to 1,100+ curated coffees with tasting profiles, brew recipes, pairings, and where-to-buy links.
Percolate is the specialty coffee journal for iOS — get it on the App Store.
Tools
| Tool | What it does |
|---|---|
| search_coffees | Catalog search with category, roast level, brew method, and price filters |
| get_coffee | Full record for one coffee: roast, body/acidity/sweetness, flavors, pairings, retailers |
| find_similar | Similar coffees by flavor overlap and roast/body/acidity proximity |
| get_recommendations | Picks from flavor preferences + budget + roast + your brew gear |
| compare_coffees | Side-by-side: profiles, shared/distinct flavors, price delta |
| trending_coffees | What Percolate users are adding to their collections right now |
| dial_in_suggestion | Brew guidance for a specific coffee — curated recipes (ratio, temp, grind) from the catalog, or a roast-based starting point |
| what_to_brew | A coffee for right now — evening picks lean decaf, mornings lean bright |
Every response includes source attribution, a citation-ready summary line, links, and data freshness dates. All scoring is deterministic — no AI calls happen inside the server. All tools are annotated read-only/idempotent.
Install (Claude Desktop)
Requires Node.js 18+.
Add to your claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config):
Restart Claude Desktop. No API key or configuration needed — the server ships with public read-only access.
Configuration (optional)
Environment variables override the defaults (explicit env vars only — this package never reads .env files):
| Variable | Purpose |
|---|---|
| SUPABASE_URL | Override the database URL |
| SUPABASE_SERVICE_ROLE_KEY | Internal use only — unlocks live 30-day collection-add trending. Never distribute this key. |
Without the service key, trending_coffees falls back to catalog popularity and labels the method in its response.
Remote endpoint (no install)
Streamable HTTP for web agents and MCP clients that take a URL:
Also listed on Smithery and the official MCP registry as io.github.bguillow-rgb/percolate.
Example agent requests
Questions an agent can answer with these tools:
- *"Recommend a medium roast with chocolate and nutty notes."* → get_recommendations with preferences: ["chocolate","nutty"], roast_level: "medium"
- *"How should I brew this Onyx Monarch on a V60?"* → dial_in_suggestion (curated recipes: ratio, temperature, grind)
- *"What coffee works for espresso under $20?"* → search_coffees with brew_method: "espresso", price_max: 20
- *"What should I brew tonight?"* → what_to_brew (evening picks lean decaf automatically)
- *"Find me something similar to this Ethiopian natural."* → find_similar