{
  "markdown": "# Percolate MCP Server\n\nQuery 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.\n\nPercolate is the specialty coffee journal for iOS — [get it on the App Store](https://apps.apple.com/us/app/percolate-specialty-coffee/id6786252100).\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `search_coffees` | Catalog search with category, roast level, brew method, and price filters |\n| `get_coffee` | Full record for one coffee: roast, body/acidity/sweetness, flavors, pairings, retailers |\n| `find_similar` | Similar coffees by flavor overlap and roast/body/acidity proximity |\n| `get_recommendations` | Picks from flavor preferences + budget + roast + your brew gear |\n| `compare_coffees` | Side-by-side: profiles, shared/distinct flavors, price delta |\n| `trending_coffees` | What Percolate users are adding to their collections right now |\n| `dial_in_suggestion` | Brew guidance for a specific coffee — curated recipes (ratio, temp, grind) from the catalog, or a roast-based starting point |\n| `what_to_brew` | A coffee for right now — evening picks lean decaf, mornings lean bright |\n\nEvery 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.\n\n## Install (Claude Desktop)\n\nRequires Node.js 18+.\n\nAdd to your `claude_desktop_config.json` (Claude Desktop → Settings → Developer → Edit Config):\n\n```json\n{\n  \"mcpServers\": {\n    \"percolate\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"percolate-mcp\"]\n    }\n  }\n}\n```\n\nRestart Claude Desktop. No API key or configuration needed — the server ships with public read-only access.\n\n## Configuration (optional)\n\nEnvironment variables override the defaults (explicit env vars only — this package never reads .env files):\n\n| Variable | Purpose |\n|---|---|\n| `SUPABASE_URL` | Override the database URL |\n| `SUPABASE_SERVICE_ROLE_KEY` | Internal use only — unlocks live 30-day collection-add trending. Never distribute this key. |\n\nWithout the service key, `trending_coffees` falls back to catalog popularity and labels the method in its response.\n\n## Remote endpoint (no install)\n\nStreamable HTTP for web agents and MCP clients that take a URL:\n\n```\nhttps://wmpiabzlcaqyrzxvfihi.supabase.co/functions/v1/mcp\n```\n\nAlso listed on [Smithery](https://smithery.ai/servers/bguillow/percolate) and the [official MCP registry](https://registry.modelcontextprotocol.io) as `io.github.bguillow-rgb/percolate`.\n\n## Example agent requests\n\nQuestions an agent can answer with these tools:\n\n- *\"Recommend a medium roast with chocolate and nutty notes.\"* → `get_recommendations` with `preferences: [\"chocolate\",\"nutty\"], roast_level: \"medium\"`\n- *\"How should I brew this Onyx Monarch on a V60?\"* → `dial_in_suggestion` (curated recipes: ratio, temperature, grind)\n- *\"What coffee works for espresso under $20?\"* → `search_coffees` with `brew_method: \"espresso\", price_max: 20`\n- *\"What should I brew tonight?\"* → `what_to_brew` (evening picks lean decaf automatically)\n- *\"Find me something similar to this Ethiopian natural.\"* → `find_similar`\n- *\"Compare these two bags.\"* → `compare_coffees`\n\nExample response shape (truncated):\n\n```json\n{\n  \"method\": \"curated_pairing\",\n  \"recipes\": [\n    { \"recipe\": \"Pour-over (V60), 1:16, 205°F\",\n      \"why\": \"clarity that lets the delicate, high-acid notes open up\" }\n  ],\n  \"attribution\": {\n    \"source\": \"Percolate — Specialty Coffee Journal\",\n    \"links\": { \"website\": \"https://percolateapp.com/\" }\n  }\n}\n```\n\n## Development\n\n```bash\nnpm install\nnpm run dev     # run from TypeScript via tsx\nnpm run build   # compile to dist/\nnpm start       # run compiled server\n```\n\nThe 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.\n\n**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.\n\n## Data & attribution\n\nCoffee data, tasting profiles, brew recipes, and pairings are curated by Percolate. Retailer links may be affiliate links. Quote freely with attribution:\n\n> Source: Percolate — Specialty Coffee Journal (percolateapp.com)\n\nFreshness dates on each coffee reflect the last data update.\n",
  "bytes": 4767,
  "sha": "72bf179479b3fa0724145d03e9eac43976ab30e5b0259d6db9d78f709cf2d838",
  "repo_slug": "bguillow-rgb/percolate-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_bguillow_rgb_percolate_0bf9d089/readme"
}