Content
# Tool List
> A **read-only query** MCP server for Freshippo's real data. Based on the reverse engineering of the Freshippo WeChat mini-program,
> it encapsulates **tested and anonymous callable** interfaces - no login, no packet capture, no ordering, no adding to cart.
## Features
| Tool | Function | Data |
|------|------|------|
| `hema_product(item_id)` | Query product details by ID: title / regular price / origin / image | ✅ Real |
| `hema_stores(city, district)` | Query Freshippo stores in a city (995 stores nationwide) | ✅ Real |
| `hema_categories(shop_id)` | Query product categories for a store (level 1 category + catId) | ✅ Real |
| `hema_shop_info(shop_id)` | Query store full name / business type / coordinates / locationId by digital store ID | ✅ Real |
| `hema_nearby_poi(geo)` | Query nearby locations by latitude and longitude (Freshippo address association) | ✅ Real |
| `recommend_snacks(...)` | Snack recommendations (built-in mock data for demonstration) | 🎭 Demo |
> Example: `hema_product("650472945903")` → Thai Golden Pillow Frozen Durian Pulp 300g/box, ¥39.9, origin: Thailand.
## Limitations
- **Member price**: `memberPrice` is always 0 when anonymous, requires login to Freshippo X membership
- **Product list under a category**: `classifyitemV3` returns empty when anonymous, requires login session
- **Inventory / add to cart / ordering**: all require login status (and add to cart interface marked `needLogin`)
To bypass these limitations, you need the login status token, which is protected by certificate pinning (network layer) + encrypted storage (local layer),
making it difficult for ordinary devices to obtain (requires rooted devices + SSL Kill Switch or Windows WeChatOpenDevTools to capture login status requests).
## Technical Details
- Gateway `acs.m.taobao.com`, appKey `12574478` (Freshippo WeChat mini-program)
- Signature `sign = md5(token & t & appKey & data)`, token from the first response `_m_h5_tk` cookie (anonymous handshake)
- Store list from Freshippo official OSS: `hema-infra-center.oss-cn-zhangjiakou.aliyuncs.com/lnc/store.json`
## Usage
```bash
git clone https://github.com/TomEageer/hema-snack-mcp.git
cd hema-snack-mcp
python3 -m venv .venv && .venv/bin/pip install -e .
```
Add the following configuration to your MCP client (Claude Code / Claude Desktop / Cursor):
```json
{
"mcpServers": {
"hema-snack": {
"command": "/absolute/path/to/hema-snack-mcp/.venv/bin/python",
"args": ["-m", "hema_snack_mcp.server"]
}
}
}
```
Restart the client and you're ready:
> "Query Freshippo itemId 650472945903"
> "What Freshippo stores are in Chengdu Jinniu District"
> "What categories does store 189031339 have"
## Disclaimer
For personal learning and self-use only, not affiliated with Alibaba/Freshippo, non-official project. Please comply with Freshippo's user agreement and avoid high-frequency requests.
This project intentionally does not implement any ordering, payment, or add-to-cart functions.
