price-verify-mcp

MCP server for price verification via the Serper API (Google Shopping + merchant page scraping).

Built to solve the problem of Google Shopping responses being too large and blowing up the LLM context: all data is truncated and reformatted server-side before being returned to the model. A price check consumes ~50 tokens instead of several thousand.

Exposed tools

Tool	Role	Output
verify_price	Searches a product on Google Shopping, keeps only the top N offers (default 3, max 5) with reduced fields (title, price, merchant, rating, delivery). Optional verdict vs expected price (in line / more expensive / cheaper, ±10 % tolerance by default).	Compact text + structured JSON
scrape_price	Scrapes a merchant product page and extracts only the price (schema.org JSON-LD first, then text regex). One price, minimal context.	Compact text + structured JSON
cache_stats	Internal cache state (diagnostic).	JSON

Why not a Serper "pass-through" server (e.g. go-serper-mcp-server)?

Those servers return the full raw Serper JSON (all offers, imageUrl, 300-character links, indented), and num is ignored by Serper's shopping endpoint (fixed Google Shopping grid). Result: tens of thousands of tokens per call. Here, truncation happens inside the MCP server, not via the num parameter.

Installation

Requirements: Node.js ≥ 18 (only for the local development option; npx handles everything else).

Option 1 — Via npx, directly from GitHub (recommended)

No local install: npx downloads and runs the server on the fly. The repo contains a package.json with a bin field, so npx can execute it directly:

{
  "mcpServers": {
    "price-verify": {
      "command": "npx",
      "args": ["-y", "github:Llamatron2112/price-verify-mcp"],
      "env": {
        "SERPER_API_KEY": "YOUR_SERPER_KEY"
      }
    }
  }
}

Requirements: public repository, valid package.json at the root, bin field present (all already in place). The first run installs the dependencies (a few seconds). You can also pin a commit/tag: github:<YOUR_USER>/price-verify-mcp#v1.0.0.

💡 This format is accepted by any MCP client supporting stdio servers and Claude-style config: Chatbox, Claude Desktop, Cursor, VS Code (they all accept the mcpServers key).

Option 2 — Local development

git clone https://github.com/Llamatron2112/price-verify-mcp.git
cd price-verify-mcp
npm install

Where does the API key go? Two options, depending on the context:

Context	Where the key goes	File to fill
Chatbox / MCP client (recommended)	env block of the MCP server config (environment variable SERPER_API_KEY)	none — just the config
Command-line testing	.env file read by the server at startup (looked up in the current working directory, then the module directory)	.env (copy .env.example)

⚠️ Priority: if SERPER_API_KEY is defined in the environment (the MCP client case), it wins over the .env file — the server never overrides an already-defined variable. So you don't need to touch .env when the key is in the client config.

API key: https://serper.dev/ (2,500 free searches, no credit card required).

Configuration in Chatbox

Chatbox accepts the Claude format (mcpServers key) for importing an MCP server.

Method A — Via the UI (recommended)

1. Settings → MCP → Add Server
2. Paste the content of mcp.chatbox.json (Claude format, replace the key):

{
  "mcpServers": {
    "price-verify": {
      "command": "npx",
      "args": ["-y", "github:Llamatron2112/price-verify-mcp"],
      "env": {
        "SERPER_API_KEY": "YOUR_SERPER_KEY"
      }
    }
  }
}

3. Save, then enable the server in the conversation.

💡 The same claude_desktop_config.json file (identical format) can be imported as-is into Claude Desktop (Settings → Developer → Edit Config).

Method B — One-click link

npm run install-link

The script prints a chatbox://mcp/install?server=... link to open in the browser (Chatbox must be installed). It reads the mcp.chatbox.json config (Claude format) and converts it automatically to the flat format expected by the one-click link.

Quick check

node server.js   # should start without error (waits for MCP messages on stdin)
npm test         # unit tests for price parsing

Usage examples (prompts)

Simple check:

Verify the price of "Sony WH-1000XM5" with verify_price (gl=fr).

With expected price (verdict):

Use verify_price with product="Sony WH-1000XM5", expected_price=300, gl="fr". Just tell me if the price found is in line and where.

Exact price at the source:

I have this URL https://www.fnac.com/... — use scrape_price to give me the current price.

Best practices for the LLM (to add to your system prompts)

• Always pass gl/hl (e.g. fr) for localized results.
• verify_price: use a precise query (brand + model + variant) to avoid heterogeneous offers.
• limit: keep 3 by default, 5 maximum.
• Don't copy the structured JSON into the answer — reply in 1–2 lines (price, merchant, verdict).
• scrape_price: reserve for already-known URLs (2nd step), as a scrape can be slower.
• Prices are displayed in the currency's natural format (e.g. 299,99 € for EUR, $1,299.99 for USD, £299.99 for GBP), detected automatically from the offer string.

Project structure

price-verify-mcp/
├── server.js              # MCP server (stdio) + tool definitions
├── lib/
│   ├── serper.js          # Serper API client (shopping + scrape)
│   ├── prices.js          # Price parsing (FR/US), verdicts, JSON-LD/regex extraction
│   └── cache.js           # In-memory TTL cache (6 h shopping, 1 h scrape)
├── scripts/install-link.js # Generates the Chatbox one-click link
├── test/prices.test.js     # Unit tests
├── mcp.chatbox.json        # Chatbox config (Claude format)
├── claude_desktop_config.json # Claude Desktop config (identical)
├── .env.example            # Configuration template
├── .gitignore              # node_modules, .env, *.tgz
├── LICENSE                 # MIT
└── package.json            # bin: price-verify-mcp (required for npx)

Known limitations

• num ignored by Serper shopping: limiting is done server-side (limit), not via the API.
• Google Shopping gives indicative prices; the exact price at the source requires scrape_price (some anti-bot or JS-only pages cannot be scraped).
• In-memory cache: cleared on server restart.
• 1 Serper key = 1 shared quota (2,500 free searches, then paid credits).

License

MIT