Percolate
Search the Percolate specialty coffee database: 1,100+ coffees with brew recipes and pairings.
Open source Repository Open in the app JSON README (API)
About
Search the Percolate specialty coffee database: 1,100+ coffees with brew recipes and pairings.
Details
- Kind
- MCP servers
- Topic
- Databases
- Publisher
- bguillow-rgb
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.1
- Last push
- 2026-09-07T11:49:44Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:31
- Updated
- 2026-08-29 03:02:31
- Origin id
io.github.bguillow-rgb/percolate
README
# Percolate MCP Server
Query the [Percolate](https://percolateapp.com/) 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](https://apps.apple.com/us/app/percolate-specialty-coffee/id6786252100).
## 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:
```
https://wmpiabzlcaqyrzxvfihi.supabase.co/functions/v1/mcp
```
Also listed on [Smithery](https://smithery.ai/servers/bguillow/percolate) and the [official MCP registry](https://registry.modelcontextprotocol.io) 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.