hema-snack-mcp

Read-only Freshippo lookup MCP

Tang Yijia (Tom)

Category: AI & MCP
Platform: Python · MCP server
License: MIT

A read-only MCP server that lets Claude look up Freshippo (Hema) products, stores and categories, using only requests that work without logging in.

Web demoAn agent chaining tools step by step

Python
MCP
FastMCP
stdio
Read-only

Try it in your browser

Everything below runs in your browser. Every response is canned sample data with fictional stores, products and IDs. Nothing here is live Freshippo data, and the page makes no network requests. The real server is read-only and meant for learning and personal use.

Playground

Pick a tool, edit the arguments, and call it. The page plays both sides: a minimal MCP client builds the JSON-RPC request, and a canned server answers with the same text shape the real one returns.

How an agent chains the tools

A scripted run of what an LLM client might do with one question. Step through it: each tool call gets a simulated reply, and later calls reuse values from earlier results.

Canned for illustration. A real client chooses its own calls.

What it can’t get anonymously

The server only uses requests that work without a login. These were tested and are gated behind a signed-in session, so the server doesn’t attempt them:

Member price: the detail payload carries a member-price field, but anonymously it is always 0.
Item lists inside a category: the category endpoint returns the tree, but the items under each category come back empty without a session.
Stock, cart and checkout: all require a login. The project deliberately implements no add-to-cart, ordering or payment at all.

Add it to your client

1. Install

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: add to the MCP config (e.g. 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: one command

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

Replace /absolute/path/to with wherever you cloned the repo, then restart the client.

How it works

A small Python server built on the official MCP SDK (FastMCP), talking to the client over stdio. Six tools; input schemas are generated from the function signatures.
Product, category, store-detail and nearby-place lookups are signed anonymous requests to the same gateway the Freshippo mini-program uses, with no account or session involved. The store directory comes from Freshippo’s public nationwide store list.
Responses are reduced to short plain-text summaries, so the model gets a few readable lines instead of a large payload.
recommend_snacks is the one demo tool: a filter-then-score ranker (flavour match, log-scaled popularity, rating, discount, a healthy bonus) over a built-in mock catalogue. The playground above runs a port of that scorer.

Scope and disclaimer

A personal learning project. It is not affiliated with Alibaba or Freshippo and is not official. It only reads publicly reachable data, deliberately has no cart, ordering or payment code, and should not be used for high-frequency requests. Please respect Freshippo’s terms of service.