percolate-mcp
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., "@percolate-mcp Recommend a medium roast with chocolate and nutty notes"
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.
Percolate MCP Server
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 |
| Catalog search with category, roast level, brew method, and price filters |
| Full record for one coffee: roast, body/acidity/sweetness, flavors, pairings, retailers |
| Similar coffees by flavor overlap and roast/body/acidity proximity |
| Picks from flavor preferences + budget + roast + your brew gear |
| Side-by-side: profiles, shared/distinct flavors, price delta |
| What Percolate users are adding to their collections right now |
| Brew guidance for a specific coffee — curated recipes (ratio, temp, grind) from the catalog, or a roast-based starting point |
| 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.
Related MCP server: coffee-price-mcp
Install (Claude Desktop)
Requires Node.js 18+.
Add to your claude_desktop_config.json (Claude Desktop → Settings → Developer → Edit Config):
{
"mcpServers": {
"percolate": {
"command": "npx",
"args": ["-y", "percolate-mcp"]
}
}
}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 |
| Override the database URL |
| 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:
https://wmpiabzlcaqyrzxvfihi.supabase.co/functions/v1/mcpAlso 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_recommendationswithpreferences: ["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_coffeeswithbrew_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"Compare these two bags." →
compare_coffees
Example response shape (truncated):
{
"method": "curated_pairing",
"recipes": [
{ "recipe": "Pour-over (V60), 1:16, 205°F",
"why": "clarity that lets the delicate, high-acid notes open up" }
],
"attribution": {
"source": "Percolate — Specialty Coffee Journal",
"links": { "website": "https://percolateapp.com/" }
}
}Development
npm install
npm run dev # run from TypeScript via tsx
npm run build # compile to dist/
npm start # run compiled serverThe server speaks MCP over stdio. Catalog access is read-only by construction: every query path issues SELECTs against tables that are publicly readable under row-level security, and it is rate-limited to 60 calls/minute.
Usage telemetry: each tool call logs the tool name, its arguments, client name/version, duration, and success/failure to a write-only log table (insert-only under RLS; contents are not publicly readable; purged after 90 days). No user identity, account data, or conversation content is collected. Logging is fire-and-forget and never affects responses.
Data & attribution
Coffee data, tasting profiles, brew recipes, and pairings are curated by Percolate. Retailer links may be affiliate links. Quote freely with attribution:
Source: Percolate — Specialty Coffee Journal (percolateapp.com)
Freshness dates on each coffee reflect the last data update.
Available Tools
8 toolscompare_coffeesCompare two coffeesARead-onlyIdempotentInspect
Side-by-side comparison: roast, body/acidity/sweetness, shared and distinct flavors, brew methods, and price difference.
Inputs: coffee_a (required), coffee_b (required).
dial_in_suggestionDial in this coffeeARead-onlyIdempotentInspect
Brew guidance for a specific coffee: curated recipes from the Percolate catalog (ratio, temperature, grind) when available, or a roast-based starting point. Optionally scoped to your brew method.
Inputs: coffee (required), brew_method.
find_similarFind similar coffeesARead-onlyIdempotentInspect
Coffees with a similar profile to a given one, ranked by shared flavor notes and roast/body/acidity/sweetness proximity. Deterministic scoring over Percolate's structured tasting data.
Inputs: coffee (required), limit.
get_coffeeGet coffee detailsARead-onlyIdempotentInspect
Detailed record for one coffee: roast level, body/acidity/sweetness profile, flavor notes, suited brew methods, food and brew pairings, price, and retailer links. Accepts a Percolate id or a name.
Inputs: id_or_name (required).
get_recommendationsGet personalized recommendationsARead-onlyIdempotentInspect
Personalized coffee picks from flavor preferences (e.g. 'chocolate', 'berry', 'caramel'), a budget in USD, roast preference, and the brew gear you own.
Inputs: preferences (required), limit, budget, brew_method, +1 more.
search_coffeesSearch the Percolate catalogARead-onlyIdempotentInspect
Search 1,100+ curated specialty coffees in the Percolate database. Filter by category (espresso, single_origin, blend, decaf, dark), roast level, brew method, and price (USD). Returns tasting profiles, brew methods, and where-to-buy links.
Inputs: limit, query, category, price_max, +3 more.
trending_coffeesTrending coffeesARead-onlyIdempotentInspect
Coffees Percolate users are adding to their collections most over the last 30 days (falls back to catalog popularity when live activity data is unavailable). The method used is labeled in the response.
Inputs: limit.
what_to_brewWhat should I brew?ARead-onlyIdempotentInspect
A coffee suggestion for right now, based on time of day (evening picks lean decaf), mood, and the brew method you're using — scored over Percolate's tasting profiles.
Inputs: mood, brew_method, time_of_day.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools are distinct, but what_to_brew, get_recommendations, find_similar, and trending_coffees all exist to surface coffee suggestions with different inputs. An agent looking for 'a recommendation' could plausibly select the wrong one if it doesn't carefully parse the trigger context.
The majority of tools follow a clean verb_noun snake_case pattern like search_coffees, get_coffee, and compare_coffees. Minor deviations such as what_to_brew and trending_coffees break the pattern slightly, but the overall naming remains predictable and readable.
Eight tools are well-scoped for a specialty coffee discovery and brewing guidance domain. Each tool serves a clearly useful purpose, and the count feels complete without being bloated or thin.
The server covers the full coffee exploration journey: search, detailed lookup, comparison, similar coffees, personalized recommendations, trending picks, and dial-in brewing advice. Minor gaps exist around explicit catalog facets or lightweight list/browse operations, but agents can work around those with search filters.
Maintenance
Related MCP Connectors
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Public MCP server for discovering open jobs. Search, filter, and get application links.
2,000+ MCP servers read at source level. Know what one does before you connect. Free, no key.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for querying and managing multiple databases (SQLite, PostgreSQL, MySQL) with read-only mode and schema inspection.13MIT
- AlicenseAqualityDmaintenanceA read-only MCP server that wraps the coffee.pryzm.gg public API to calculate effective prices of coffee drinks after discounts, enabling users to find the cheapest coffee deals, search for discounts, and verify receipt prices.32MIT
- FlicenseAqualityDmaintenanceRead-only PostgreSQL database MCP server for safely exploring schema, tables, relationships, and sample data without modification.10-
- AlicenseAqualityDmaintenanceAn MCP server that finds great espresso cafes using a curated database of specialty coffee shops and a transparent scoring algorithm, with a strong bias against flavored syrups and mass-market chains.647 npmMIT