Skip to main content
Glama
percolate-mcp

percolate-mcp

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.

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

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

Available Tools

8 tools
compare_coffeesCompare two coffeesA
Read-onlyIdempotent
Inspect

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 coffeeA
Read-onlyIdempotent
Inspect

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 coffeesA
Read-onlyIdempotent
Inspect

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 detailsA
Read-onlyIdempotent
Inspect

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 recommendationsA
Read-onlyIdempotent
Inspect

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 catalogA
Read-onlyIdempotent
Inspect

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.

what_to_brewWhat should I brew?A
Read-onlyIdempotent
Inspect

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

    A3.9/5.0

    Scored across 8 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for querying and managing multiple databases (SQLite, PostgreSQL, MySQL) with read-only mode and schema inspection.
      13
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      3
      2
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Read-only PostgreSQL database MCP server for safely exploring schema, tables, relationships, and sample data without modification.
      10
      -
    • A
      license
      A
      quality
      D
      maintenance
      An 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.
      6
      47 npm
      MIT