webhallen-mcp

An unofficial Model Context Protocol server that lets AI assistants (Claude, ChatGPT, and any other MCP client) search products, check prices and store stock, and read reviews on Webhallen, the Swedish electronics and gaming retailer.

⚠️ Unofficial / use at your own risk. Webhallen does not offer a public API. This server talks to the same internal JSON endpoints their website uses, so there's no stability guarantee: Webhallen can change or block them at any time. Respect their Terms of Service and robots.txt, keep request volume low, and don't use this to resell their data. Provided as-is under the MIT license with no affiliation to Webhallen Sverige AB.

Tools

Related MCP server: ozon-customer-mcp

How it works

webhallen.com is a Vue SPA on top of a plain JSON REST API under /api/. No auth or special headers are needed for catalog data:

• Search → GET /api/productdiscovery/search/<query>?page=&sortBy=&filters[n]=

• Category → GET /api/productdiscovery/category/<id>?page=&sortBy=&filters[n]=

• Product → GET /api/product/<id>

• Reviews → GET /api/reviews?product=<id>&page=

• Stores → GET /api/store/se

Filters use the same encoding the storefront builds, <attribute>-<type>-<v1~v2>, e.g. brand-1-Kingston~Samsung, price-3-1000~2000 or custom.has_stock-1-web, so filtering happens on Webhallen's side and pages come back full.

Some things worth knowing about the API:

• Unknown /api/ paths don't 404, they return the SPA's HTML with a 200. The HTTP client checks the content type, so a moved endpoint shows up as a clear error instead of a JSON parse failure.

• Listing endpoints always return 24 products per page; there's no page-size parameter.

• stock is a flat object where numeric keys are store ids ({ "web": 16, "2": 0, "5": 3, ... }), and quantities are capped at displayCap (50).

• Instead of a price history, Webhallen exposes lowestPrice: the lowest price in the last 30 days, which Swedish shops have to show next to a discount (EU Omnibus directive).

• There's no category-by-name endpoint, so list_category searches for the name and picks the best match from the category tree that comes back with the results.

Every request goes through a small rate limiter, a bounded short-lived response cache, and a timeout.

Install

npm install
npm run build

Use with Claude Code

claude mcp add webhallen -- node /absolute/path/to/webhallen-mcp/dist/index.js

Use with Claude Desktop / other MCP clients

Add to your client's MCP config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "webhallen": {
      "command": "node",
      "args": ["/absolute/path/to/webhallen-mcp/dist/index.js"]
    }
  }
}

Configuration (env vars)

Development

npm test        # builds, then runs the unit tests in test/
npm run dev     # tsc --watch

The tests cover the parsing/mapping layer (src/parse.ts) against payloads captured from the live API, so they run offline.

Project layout

src/
  index.ts            MCP server + tool registration
  config.ts           env-driven config (base url, rate limits, cache)
  types.ts            normalized models + DataProvider interface
  http.ts             HTTP client (throttle + cache + timeout)
  parse.ts            pure helpers mapping the wire format to the models
  providers/
    rest.ts           internal REST API provider
test/
  parse.test.js       unit tests for parse.ts

The tools talk to a DataProvider interface rather than the REST client directly, so the data source can be swapped out later if the internal API stops working.

License

MIT