Percolate

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

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):

{

"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):

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/mcp

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
• *"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 server

The 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.