内容
# 🛒 hema-snack-mcp · 盒马商品查询 MCP
> 一个**只读查询**盒马（Freshippo）真实数据的 MCP server。基于对盒马微信小程序的逆向，
> 封装了**实测可匿名调用**的接口——不登录、不抓包、不下单、不加购。
## ✨ 能查什么（都是真实数据）
| 工具 | 作用 | 数据 |
|------|------|------|
| `hema_product(item_id)` | 按商品 ID 查详情：标题 / 常规价 / 产地 / 图 | ✅ 真实 |
| `hema_stores(city, district)` | 查某城市的盒马门店（全国 995 家） | ✅ 真实 |
| `hema_categories(shop_id)` | 查某门店的商品分类树（一级类 + catId） | ✅ 真实 |
| `hema_shop_info(shop_id)` | 按数字门店 ID 查门店全名 / 业态 / 坐标 / locationId | ✅ 真实 |
| `hema_nearby_poi(geo)` | 按经纬度查附近地点（盒马地址联想） | ✅ 真实 |
| `recommend_snacks(...)` | 零食推荐（内置 mock 数据，演示交互用） | 🎭 演示 |
> 示例：`hema_product("650472945903")` → 泰国金枕头冷冻榴莲肉 300g/盒，¥39.9，产地泰国。
## ⛔ 查不到什么（盒马登录态门控，匿名拿不到，已实测）
- **会员价**：详情里 `memberPrice` 匿名恒为 0，需登录盒马 X 会员
- **某分类下的商品列表**：`classifyitemV3` 匿名返回空，需登录会话
- **库存 / 加购 / 下单**：全部需要登录态（且加购接口标 `needLogin`）
要突破这些得登录态令牌，而它被证书钉死（网络层）+ 加密存储（本地层）双重保护，
普通设备拿不到（需越狱机 + SSL Kill Switch，或 Windows 上 WeChatOpenDevTools 抓登录态请求）。
## 🔧 技术细节
- 网关 `acs.m.taobao.com`，appKey `12574478`（盒马微信小程序）
- 签名 `sign = md5(token & t & appKey & data)`，token 取自首响应 `_m_h5_tk` cookie（匿名握手）
- 门店名录来自盒马官方 OSS：`hema-infra-center.oss-cn-zhangjiakou.aliyuncs.com/lnc/store.json`
## 🚀 用法
```bash
git clone https://github.com/TomEageer/hema-snack-mcp.git
cd hema-snack-mcp
python3 -m venv .venv && .venv/bin/pip install -e .
```
在 MCP 客户端（Claude Code / Claude Desktop / Cursor）配置里加入，把路径换成你 clone 的实际路径：
```json
{
"mcpServers": {
"hema-snack": {
"command": "/absolute/path/to/hema-snack-mcp/.venv/bin/python",
"args": ["-m", "hema_snack_mcp.server"]
}
}
}
```
重启客户端后即可：
> "查下盒马 itemId 650472945903"
> "成都金牛区有哪些盒马"
> "门店 189031339 有哪些分类"
## ⚠️ 免责
仅供个人学习/自用，与阿里巴巴/盒马无关，非官方项目。请遵守盒马用户协议，勿高频请求。
本项目刻意不实现任何下单、支付、加购功能。
