Espresso MCP

espresso-mcp

一款能寻找优质意式浓缩咖啡馆，并将其优质之处整理成规则的 MCP 服务。

espresso-mcp 是一款 Model Context Protocol 服务，可接入 Claude Desktop、Claude.ai、ChatGPT、Google Gemini、Cursor、Hermes、OpenClaw 以及任何其他标准 MCP 宿主。它自带一个精心整理的数据库，收录了 100 多家精品咖啡馆、75 多家精品烘焙商，以及一套透明的评分算法，用来呈现一家店为何出色——从咖啡豆采购、新鲜度、设备到培训——以及为何不佳（最重的负面信号是菜单被风味糖浆饮品占据）。

它不是 Yelp 的克隆。数据经过人工整理，评分标准明确，理念是：“如果一家店用风味掩盖劣质咖啡，我们就不想要它。”

---

评分倾向

espresso-mcp 有自己的判断。用风味糖浆掩盖劣质咖啡的店铺，正是这款工具旨在筛除的典型问题。评分算法对 syrup_emphasis 施加最重的非淘汰性惩罚（−22），比任何单一正面信号的权重都更高。大众连锁品牌（Starbucks、Dunkin'、Costa、Tim Hortons、Peet's、Caribou）以及“看起来像第三波咖啡馆，喝起来却满是风味”的店铺（算法中的 flavor-led-specialty 类别），无论招牌看起来多么漂亮，得分都会落在 avoid 或 fair 档。

优质店铺真正投入的方面会获得正向加分：

• 店内烘焙，或从知名精品烘焙商处采购并注明合作方
• 单一产地意式浓缩咖啡（而非只有拼配）
• 零售咖啡豆包装上标注烘焙日期（体现对最佳新鲜度的承诺）
• 同时提供意式浓缩和手冲——即“完整咖啡项目”
• 菜单上有澳白——这是一项信心指标；如果意式浓缩不够出色，店家通常会避开小杯奶咖
• 参与赛事 / 员工持有 SCA 认证
• 使用第三波咖啡馆优选设备（Slayer、La Marzocco、Synesso、Decent、Victoria Arduino、Modbar）
• 获得权威榜单认可（World's 100 Best、SCA 锦标赛、Coffee Review 95+、Good Food Awards）

每项信号都记录在 src/scoring/weights.ts 中，并通过每条结果的评分明细呈现给客户端——你可以清楚看到推荐一家咖啡馆的具体原因。

---

查看实际效果

You: I'm near Brandenburg Gate in Berlin. Find me 3 great espresso cafes 
     within walking distance.

Claude: [resolves Brandenburg Gate → 52.5163, 13.3777]
        [calls find_espresso_near with radius_km=2]

  Found 3 specialty cafes within 2km of Brandenburg Gate, sorted by quality:

  • The Barn (Mitte)         — 0.8km — score 95 (world-class) — World's #61
    In-house roastery, single-origin focus, "never blends beans." Founded 
    2010, one of Europe's leading third-wave roasters.

  • Companion Coffee (Mitte) — 1.1km — score 83 (great)
    Curated multi-roaster with rotating guest beans. Tea + coffee crossover 
    in a quiet Mitte design space.

  • Westberlin (Mitte)       — 1.3km — score 82 (great)
    Iconic third-wave anchor since ~2010. Magazine + coffee concept; pours 
    The Barn and rotating European roasters.

---

功能介绍

安装到 MCP 客户端后，你可以这样提问：

• “我在柏林的 Hotel Adlon——帮我找一家步行可达的优质意式浓缩咖啡馆。”
• “我住在勃兰登堡门附近。推荐 3 家咖啡馆并按品质排序。”
• “搜索东京评分高于 80 的咖啡馆。”
• “介绍一下 Tim Wendelboe。”
• “给这家咖啡馆打分——他们有 Slayer 咖啡机、店内烘焙、单一产地意式浓缩，而且不使用风味糖浆。”
• “丹麦有哪些世界级烘焙商？”
• “在芝加哥有哪些店应该避开？举一个反面案例。”

模型会提供包含理由、距离、奖项和各项信号贡献的结构化评分，让你得到真实可靠的推荐，而不是一份按人气排列的名单。

---

快速安装

客户端	章节
Claude Desktop	↓
Claude.ai（浏览器 MCP）	↓
ChatGPT	↓
Google Gemini CLI	↓
Hermes（Nous Research）	↓
OpenClaw	↓
Cursor	↓
VS Code	↓
任意标准 stdio 客户端	↓
从源代码安装	↓

建议：项目仍在迭代时使用 @latest

在我们继续添加咖啡馆并优化算法期间，请固定到 npm 的最新版本：

"args": ["-y", "espresso-mcp@latest"]

数据和评分稳定后，你可以去掉 @latest，改为固定到特定版本，以确保可复现。

---

各客户端的配置

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。如果文件不存在，请创建：

{
  "mcpServers": {
    "espresso": {
      "command": "npx",
      "args": ["-y", "espresso-mcp@latest"]
    }
  }
}

重启 Claude Desktop。🔌 菜单中应会在「espresso」下显示 6 个工具。

Claude.ai（浏览器 MCP）

Claude.ai 网页应用通过 OAuth 和远程端点支持 MCP 服务。本地安装请改用 Claude Desktop（见上文）。若要将 espresso-mcp 作为远程服务提供给 Claude.ai，请使用 mcp-remote 封装（参见下文的 ChatGPT 部分，方法相同）。

ChatGPT

⚠ 重要：ChatGPT 仅支持远程 MCP 服务（HTTPS 端点），不支持本地 stdio 进程。你有两种选择：

选项 1：使用托管版本（如果可用）。 如果我们发布托管端点，会在此处列出。

选项 2：通过 mcp-remote 将 espresso-mcp 桥接到 HTTPS。 在你控制的机器上运行一个小型桥接程序：

npx -y mcp-remote bridge espresso-mcp \
  --port 8080 \
  --token "your-shared-secret"

然后通过隧道（Cloudflare Tunnel、Tailscale Funnel 或小型 VPS）暴露 8080 端口，并使用生成的 HTTPS URL。

在 ChatGPT 中启用 MCP（仅限 Plus / Pro / Team / Enterprise 方案）：

1. Settings → Connectors → Advanced → 开启 Developer mode。
2. 添加一个指向桥接 URL 的自定义连接器。

OpenAI 的 MCP 文档提供了最新的连接器设置说明。

Google Gemini CLI

编辑 ~/.gemini/settings.json：

{
  "mcpServers": {
    "espresso": {
      "command": "npx",
      "args": ["-y", "espresso-mcp@latest"]
    }
  }
}

重启 Gemini CLI。它会在启动时自动连接，成功后显示「Connected」。完整参考请参阅 Gemini CLI MCP 文档。

Hermes（Nous Research）

Hermes 使用 YAML，而不是 JSON。编辑 ~/.hermes/config.yaml：

mcp_servers:
  espresso:
    command: "npx"
    args: ["-y", "espresso-mcp@latest"]

可选：仅筛选要公开的工具：

mcp_servers:
  espresso:
    command: "npx"
    args: ["-y", "espresso-mcp@latest"]
    tools:
      include: [find_espresso_near, search_cafes, score_cafe]

重启 Hermes——它会在启动时自动发现 MCP 工具。请参阅 Hermes MCP 文档。

OpenClaw

OpenClaw 使用标准的 stdio MCP 配置。如果你尚未安装 OpenClaw：

curl -fsSL https://openclaw.ai/install.sh | bash
# or: npm install -g openclaw@latest

然后添加到 OpenClaw 配置中（通常是 ~/.openclaw/config.json——请查看 OpenClaw MCP 文档了解当前路径）：

{
  "mcpServers": {
    "espresso": {
      "command": "npx",
      "args": ["-y", "espresso-mcp@latest"]
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "espresso": {
      "command": "npx",
      "args": ["-y", "espresso-mcp@latest"]
    }
  }
}

VS Code

VS Code 使用专用的 mcp.json 文件（而不是 settings.json）。对于工作区范围的配置，请创建 .vscode/mcp.json。对于用户范围的配置，请从命令面板运行 MCP: Open User Configuration 命令。

{
  "servers": {
    "espresso": {
      "command": "npx",
      "args": ["-y", "espresso-mcp@latest"]
    }
  }
}

注意：VS Code 使用键 servers（而不是 mcpServers）——从其他客户端迁移配置时，最常见的复制粘贴错误就是这一点。

通用 stdio 客户端

适用于任何会启动本地进程的 MCP 兼容宿主：

{
  "command": "npx",
  "args": ["-y", "espresso-mcp@latest"]
}

服务仅将 JSON-RPC 写入 stdout，将日志写入 stderr——如果需要启动消息，请捕获 stderr。

从源代码构建（开发）

git clone https://github.com/mattgierhart/espresso-mcp
cd espresso-mcp
npm ci
npm run build

# Point your client at:
#   command: node
#   args:    ["/absolute/path/to/espresso-mcp/dist/index.js"]

或者针对本地构建运行 MCP Inspector：

npm run inspect

---

旅行和基于地址的查询

最常见的实际问题是 「我在 X，应该去哪儿喝咖啡？」 以下是实际使用方法。

基于酒店的推荐

You: I'm staying at the Hotel Adlon Berlin. Find me 3 great espresso cafes nearby.

[Claude searches for the Adlon's coordinates: ~52.5163, 13.3795]
[Claude calls find_espresso_near with those lat/lon]
[Returns ranked Berlin cafes within walking distance]

模型会解析地址并获取坐标（使用其内置知识或网页搜索），然后调用 find_espresso_near。无需额外配置。

基于地址的查询

You: I'm walking around Millennium Park in Chicago. What's the closest specialty espresso?

[Claude resolves the landmark → ~41.882, -87.622]
[Calls find_espresso_near with radius_km: 2]
[Ranks results by quality, then distance]

多城市行程规划

You: I have trips coming up to Tokyo, Berlin, and Hong Kong. Build me a coffee plan —
     top 2 cafes per city, plus the one roaster I should buy beans from in each.

[Claude calls search_cafes for each city, sorts by score]
[Calls list_great_roasters filtered by country]
[Composes a per-city itinerary]

为你眼前的咖啡馆评分

You: I'm at a cafe with a Slayer machine, they roast on-site, single-origin espresso 
     option, roast date on bags, and they only have plain milk drinks — no syrups. 
     Score it.

[Claude calls score_cafe with those signals]
[Returns 95/100 ("world-class") with per-signal contributions]

酒店周边咖啡步行便利度比较（手动操作，直到 v0.4）

目前可以通过多次调用工具来实现：

You: Compare these Berlin hotels by walkable specialty coffee:
     - Hotel Adlon (Mitte)
     - Soho House Berlin (Mitte)
     - 25hours Hotel Bikini (Charlottenburg)

[Claude calls find_espresso_near three times, one per hotel]
[Composes a comparison table]

专用的 score_hotel_coffee_access 工具已列入 路线图，计划在 v0.5 推出。

尽力支持尚未录入数据库的城市

如果你查询的城市尚未经过整理（例如 Lisbon、Seoul、Mexico City），find_espresso_near 将不会返回经过整理的匹配结果。模型仍可结合自身知识与 score_cafe，评估你描述的任何咖啡馆。我们正分批补充城市数据——如果你希望优先整理你所在的城市，请提交 issue。

---

工具

find_espresso_near

查找指定坐标半径范围内的精品浓缩咖啡馆，并按排名排序。

{ "lat": 35.6855, "lon": 139.6904, "radius_km": 3, "min_score": 60, "limit": 10 }

返回经过整理的数据库中的咖啡馆，按浓缩咖啡品质得分排序，并提供每家咖啡馆的距离和评分理由。

search_cafes

按查询词、城市、国家、烘焙商或最低分数搜索经过整理的数据库。

{ "query": "natural wine", "country": "DE", "min_score": 70, "limit": 20 }

get_cafe_details

按 ID 获取咖啡馆的完整记录，包括逐项评分信号明细，以及几家相关或附近的咖啡馆。

{ "id": "tim-wendelboe-oslo" }

score_cafe

直接调用已编码的算法。传入你观察到的信号（来自网站、评论或照片），即可获取 0-100 分的评分及逐项信号贡献明细。无需查询数据库。

{
  "name": "Hypothetical Shop",
  "observed_signals": {
    "roasting": "in-house",
    "brew_methods": ["espresso", "pour-over"],
    "single_origin_espresso": true,
    "roast_date_on_bags": true,
    "cortado_on_menu": true,
    "syrup_emphasis": false
  }
}

list_great_roasters

按国家和声誉等级整理的精品烘焙商列表。

{ "country": "DK", "min_reputation": "regional-leader", "limit": 25 }

list_anti_patterns

整理出可作为避雷示例的咖啡馆——也就是算法的对照组。分为两类：

• mass-market-chain — Starbucks、Dunkin'、Costa、Tim Hortons、Peet's、Caribou。普通的深度烘焙、风味饮品菜单、采购来源透明度低。
• flavor-led-specialty — 店内展示第三波咖啡标志（店内烘焙、单一产地标识、烘焙日期），但实际提供的菜单以糖浆饮品为主。看起来是精品咖啡，喝起来却是风味饮品。 在解释推荐的店为何是真正的精品咖啡馆时，这类示例很有用。

{ "category": "flavor-led-specialty", "limit": 10 }

反模式数据单独存储在 data/anti-patterns.json 中，因此绝不会混入 find_espresso_near 或 search_cafes 的结果。

---

评分方式

完整的权重表以 src/scoring/weights.ts 为准。简而言之：

正向信号（优秀咖啡馆的做法）：

• 店内烘焙，或与知名精品烘焙商合作烘焙
• 单一产地浓缩咖啡
• 零售咖啡豆包装上标注烘焙日期（体现对最佳新鲜度的坚持）
• 同时提供浓缩咖啡和手冲咖啡（“完整的咖啡项目”）
• 菜单上有 cortado（体现对浓缩咖啡的信心）
• 参与赛事／员工获得 SCA 认证
• 高品质咖啡机（Slayer、La Marzocco、Synesso、Decent、Victoria Arduino、Modbar）
• 奖项（World's 100 Best、SCA 锦标赛、Coffee Review 95+、Good Food Awards）

负向信号（掩饰问题的模式）：

• syrup_emphasis (−22) — 菜单以风味糖浆饮品为主。最强的避雷信号。优秀的咖啡馆不会靠糖浆掩盖问题。
• flavored_drink_share > 0.5（额外 −7）
• no_grinder_visible（−25）— 基本可直接排除
• only_dark_roast（−8）— 掩盖咖啡豆的缺陷
• no_origin_info（−7）— 不知道或不在乎咖啡豆的产地

烘焙商声誉加分：店内烘焙或与知名烘焙商合作的咖啡馆，除结构性信号外，还可获得 +25（世界级）、+15（区域领军者）或 +8（知名）分。

值为 null 或未知的信号会被跳过，不会扣分。评分包含一个 confidence 值，与实际观察到的信号数量成正比。

评分等级：

分数	等级
≥ 85	世界级
≥ 70	优秀
≥ 55	良好
≥ 40	一般
< 40	避雷

“看起来是精品咖啡，实则不然”的情况比较棘手——兼具真正的第三波咖啡结构性信号和风味饮品菜单的咖啡馆，即使受到糖浆惩罚，仍可能得到“良好”档的分数。对于这类情况，data/anti-patterns.json 中明确标记的 category: flavor-led-specialty 是权威的人工修正依据。

---

精选覆盖范围（v0.2.0）

数据库由人工精选。覆盖范围主要集中在我们（或可信的精选指南）近期实地走访过的城市。我们会分批添加城市——如果你希望优先收录你所在的城市，请提交 issue。

地区	咖啡馆	涵盖的街区
Berlin	15	Mitte、Kreuzberg、Neukölln、Charlottenburg
London	15	Holborn、Shoreditch、City、Marylebone、Bishopsgate、Hammersmith（包括 Workshop × 3）
NYC（Manhattan + Brooklyn）	17	East Village、Nolita、Noho、Flatiron、FiDi、NoMad、Williamsburg、Bushwick、Park Slope
Dallas / DFW	18	Design District、Lower Greenville、Oak Cliff / Bishop Arts、Deep Ellum、Knox-Henderson、Plano
Denver metro	18	Capitol Hill、RiNo、LoHi、Tennyson、Edgewater、Aurora、Lone Tree、Littleton
Hong Kong	10	Causeway Bay、Sheung Wan、Tsim Sha Tsui、Tai Hang
Tokyo / Osaka	6	Omotesando、Nakameguro、Kuramae、Shimokitazawa、Sangubashi
Guangzhou	8	Tianhe、Yuexiu、Liwan
Other	~9	Oslo、Copenhagen、Dublin、Galway、Vienna、Singapore、Santa Ana SV、Rogers AR

此外还特意标记了 8 个反面案例（Starbucks、Dunkin'、Costa、Tim Hortons、Peet's、Caribou，以及两个“看起来是精品咖啡，喝起来却是调味咖啡”的案例）。

下一步值得填补的空白：SF、LA、Seattle、Portland、Melbourne、Sydney、Stockholm、Amsterdam、Paris、Taipei、Seoul、Mexico City。

---

为咖啡馆做贡献

针对 data/cafes.json 提交 PR：

1. 按城市字母顺序排序，再按名称排序后添加条目。
2. 尽可能使用精确坐标（"coord_precision": "exact"）。请在 Google Maps 上查找。
3. 将 last_verified 设为今天的 ISO 日期。
4. 仅包含你亲自观察到或能提供来源的信号。
5. 如果要添加新的烘焙商，请将其加入 data/roasters.json，并设置合理的声誉等级（notable、regional-leader 或 world-class）。
6. 提交 PR 前运行 npm test 和 npm run validate-data。

完整的架构参考请见 data/README.md。

提交反面案例建议

反面案例应加入 data/anti-patterns.json，并设置 category 字段。合适的候选对象是你亲自核实过的店铺，它们要么属于大众市场，要么“看起来是精品咖啡，喝起来却是调味咖啡”。请添加 notes 字段，说明招牌宣传与实际体验之间的差距。

提交反馈

请提交 issue，说明你测试了什么、哪些有效、有哪些意外发现，以及还缺少什么。我们通过 open issue 跟踪路线图（社区贡献工具、自动地址地理编码、实时数据回退、酒店距离评分）。

---

许可证

• 代码采用 MIT 许可证——请见 LICENSE。
• 数据（data/*.json）采用 CC-BY 4.0 许可证——请见 data/LICENSE。须注明出处。

如果你重新分发这些数据，请链接回此代码库。

---

我们用于训练这些模式的来源

精选咖啡馆名单、信号权重表和反模式分类框架，是通过阅读并交叉参考已经擅长这项工作的相关人士的资料建立的。特此致谢并附上链接：

城市和地区指南

• 世界 100 家最佳咖啡馆 — 每年由行业投票选出的排名；世界级咖啡馆层级的基石
• 欧洲咖啡之旅 — 精选了 6,229 多家欧洲精品咖啡馆；伦敦和柏林批次主要参考了此来源
• D Magazine — 达拉斯最佳咖啡馆和烘焙商 — DFW 精品咖啡指南的权威来源
• Drips of God — 纽约 — 曼哈顿和布鲁克林的精选名单
• Bee An Coffee — 2026 年纽约市最佳精品咖啡 — 聚焦布鲁克林烘焙商
• Grounds Club — 香港精品咖啡指南 — 专为香港整理
• 亚洲咖啡地图 — 亚洲地区的主要参考来源

奖项和排名

• Sprudgie Awards — Sprudge 每年颁发的社区奖项
• Good Food Awards：咖啡 — 对美国精品咖啡烘焙商的认可
• Coffee Review（95 分以上） — 卓越的烘焙品质
• SCA 世界咖啡师大赛 — 参与竞赛是一个强信号指标

框架和分类体系

• Sprudge — 精品咖啡长篇新闻报道；最初的“信号分类体系”构想源自多年阅读 Sprudge 的积累
• 精品咖啡协会 — 咖啡师技能课程 — 设备候选清单和认证框架
• SCA 认证商用设备列表 — “优质意式咖啡机”的定义

花了很多时间泡在咖啡馆里。 实地调研。大概不能抵税。这是这份名单里最诚实的一项——src/scoring/weights.ts 中的每个权重，都是由一位曾亲身失望于某家配备 Slayer 咖啡机、实际却偏爱糖浆风味的店的人校准的。

构建所用

• @modelcontextprotocol/sdk — 官方 MCP TypeScript SDK
• Zod、tsup、Vitest、Firecrawl（用于整理城市指南时抓取内容）