hema-snack-mcp

只读的盒马商品查询 MCP

唐艺家 (Tom)

在线试用 GitHub

类别: AI 与 MCP
平台: Python · MCP Server
许可: MIT

一个只读的 MCP 服务端，让 Claude 能查盒马的商品、门店和分类。只用不登录就能调通的接口。

Python
MCP
FastMCP
stdio
只读

在浏览器里试试

下面的内容全部在浏览器里运行。所有响应都是预置的样例数据，门店、商品和 ID 都是虚构的，不是盒马的实时数据，页面也不发任何网络请求。真实的服务端是只读的，仅供学习和个人自用。

交互演示

选一个工具、改参数、点调用。页面同时扮演两端：一个极简 MCP 客户端拼出 JSON-RPC 请求，一个预置数据的“服务端”按真实工具的文本格式回复。

Agent 怎么串起这些工具

一个问题下，LLM 客户端可能的调用过程（预先写好的脚本）。逐步播放：每次工具调用都有模拟回复，后面的调用会用上前面结果里的值。

仅作示意，是预置的。真实客户端会自己决定调哪些工具。

匿名拿不到的东西

服务端只用不登录就能调通的接口。下面这些都实测过，需要登录态，所以服务端根本不去碰：

会员价: 商品详情里有会员价字段，但匿名时恒为 0。
分类下的商品列表: 分类接口能拿到分类树，但每个分类下的商品，没有登录会话就返回空。
库存、加购、下单: 全部需要登录。本项目刻意不实现任何加购、下单、支付功能。

接入你的 MCP 客户端

1. 安装

git clone https://github.com/TomEageer/hema-snack-mcp.git
cd hema-snack-mcp
python3 -m venv .venv && .venv/bin/pip install -e .

2a. Claude Desktop / Cursor：写进 MCP 配置（如 claude_desktop_config.json）

{
  "mcpServers": {
    "hema-snack": {
      "command": "/absolute/path/to/hema-snack-mcp/.venv/bin/python",
      "args": ["-m", "hema_snack_mcp.server"]
    }
  }
}

2b. Claude Code：一条命令

claude mcp add hema-snack -- /absolute/path/to/hema-snack-mcp/.venv/bin/python -m hema_snack_mcp.server

把 /absolute/path/to 换成你 clone 的实际路径，然后重启客户端。

实现思路

基于官方 MCP SDK（FastMCP）写的一个小型 Python 服务端，通过 stdio 和客户端通信。共 6 个工具，输入 schema 由函数签名自动生成。
商品、分类、门店详情、附近地点这几类查询，是向盒马小程序所用网关发起的签名匿名请求，不涉及任何账号或登录会话。门店名录来自盒马公开的全国门店列表。
返回结果会压缩成几行纯文本摘要，模型读到的是简短可读的内容，而不是一大坨原始数据。
recommend_snacks 是唯一的演示工具：先过滤再打分（口味匹配、对数压缩的销量、评分、折扣、健康加分），数据来自内置 mock 商品库。上面的调试台跑的就是这套打分逻辑的移植版。

范围与免责

个人学习项目，与阿里巴巴、盒马无关，非官方。只读取公开可达的数据，刻意不包含任何加购、下单、支付代码，请勿高频请求，并遵守盒马用户协议。