io.github.bguillow-rgb/percolate MCP Server

This MCP server provides read-only access to the Percolate specialty coffee database from an MCP-compatible AI client. It supports searching a catalog of 1,100+ coffees and retrieving full coffee records, including tasting profiles, brew recipes, pairings, and where-to-buy links.

🛠️ Key Features

Search Percolate’s specialty coffee database (1,100+ coffees)
Read-only access
Tools include search_coffees and get_coffee
Topics include agent-tools, ai-agents, brewing, coffee, mcp, model-context-protocol

🚀 Use Cases

Find coffees using filters for category, roast level, brew method, and price
Retrieve detailed information for a single coffee record

⚡ Developer Benefits

Integrates with Claude or any MCP-compatible AI client
get_coffee provides full record details for one coffee
Database entries include tasting profiles, brew recipes, pairings, and where-to-buy links

⚠️ Limitations

Read-only access (no writing or updates described)
Tool support listed: search_coffees and get_coffee (from the provided excerpt)

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

json

{
  "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
`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:

code

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

json

{
  "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

bash

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.

query	string	optional	Free-text search: coffee or roaster name
category	string	optional	Coffee category to filter by; omit to search all
roast_level	string	optional	Roast level to filter by; omit to include all roasts
brew_method	string	optional	e.g. 'espresso', 'pourover', 'french press', 'drip'
price_min	number	optional	Minimum price in USD
price_max	number	optional	Maximum price in USD
limit	integer	optional	Max results (default 10, max 10)

coffee	string	required	Coffee id or name
limit	integer	optional	Max results (default 5)

preferences	array	required	Flavors the drinker enjoys, e.g. ['chocolate','caramel','nutty']
budget	number	optional	Max price in USD per bag
roast_level	string	optional	Roast level to filter by; omit to include all roasts
brew_method	string	optional	What you brew with, e.g. 'espresso', 'pourover'
limit	integer	optional	Max results (default 5)

coffee_a	string	required	First coffee — id or name
coffee_b	string	required	Second coffee — id or name

coffee	string	required	Coffee id or name
brew_method	string	optional	Your brewer, e.g. 'V60', 'espresso', 'french press'

time_of_day	string	optional	When the coffee will be drunk — shifts the pick toward lighter or lower-caffeine options later in the day
mood	string	optional	e.g. 'need focus', 'lazy weekend', 'something comforting', 'adventurous'
brew_method	string	optional	What you're brewing with

io.github.bguillow-rgb/percolate MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

search_coffees

get_coffee

find_similar

get_recommendations

compare_coffees

trending_coffees

dial_in_suggestion

what_to_brew