Skip to main content
Glama
sven-borden

galaxus-mcp

by sven-borden
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

galaxus-mcp

An MCP server for product search and discovery on Galaxus and Digitec. Read-only: search, browse, compare, look up prices and specs. Nothing that requires a login (no cart, no orders, no account data).

Tools

Tool

What it does

galaxus_search

Full-text search. Returns products plus the facets you can narrow with.

galaxus_get_product

Everything about one product: price, stock, specs, variants, price history, warranty.

galaxus_autocomplete

Type-ahead: search-term suggestions and a few direct product hits.

galaxus_browse_category

List a category (product type) without a search term.

galaxus_browse_brand

List a brand's products.

galaxus_related_products

Alternatives (similar), complements (bought_together), add-ons (accessories).

galaxus_get_review_summary

Average rating, rating count, and the pros/cons reviewers mention most.

Every list tool supports filters, min_price / max_price, sort (RELEVANCE, LOWEST_PRICE, HIGHEST_PRICE, RATING, NEWEST, AVAILABILITY), limit and cursor pagination.

Filters are discoverable rather than hardcoded: search and browse results carry a filters block listing each facet's id and its options with counts (bra = brand, pt = category, pr = price range, rating, plus per-category spec filters such as "Signal transmission"). Feed those ids straight back in:

{ "query": "wireless mouse", "filters": [{ "filter_id": "bra", "option_ids": ["292"] }], "max_price": 80 }

Related MCP server: PriceHunt MCP Server

Setup

npm install
npm run build
npm run smoke     # exercises all 7 tools against the live shop

Then register it with Claude Code:

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

Or drop it in an MCP client config (this repo also ships a project-scoped .mcp.json):

{
  "mcpServers": {
    "galaxus": {
      "command": "node",
      "args": ["/absolute/path/to/galaxus-mcp/dist/index.js"],
      "env": { "GALAXUS_PORTAL": "galaxus", "GALAXUS_LANGUAGE": "en" }
    }
  }
}

Env var

Values

Default

GALAXUS_PORTAL

galaxus, digitec

galaxus

GALAXUS_LANGUAGE

en, de, fr, it

en

The language affects product names, specification labels and facet titles.

Using it

Once registered, just ask in natural language — the tools chain on their own:

  • "Find me a wireless mouse under CHF 100 with good reviews" → galaxus_search with max_price and sort: RATING, then galaxus_get_review_summary on the pick.

  • "What are the specs of the Logitech MX Master 3S, and has it been cheaper?" → galaxus_get_product, which carries the specs and the price-history summary.

  • "Show me alternatives to this one that are cheaper" → galaxus_related_products with kind: similar.

  • "What Logitech keyboards are in stock?" → galaxus_browse_brand with sort: AVAILABILITY.

Product ids are the trailing number in any Galaxus URL, and the product tools accept the full URL too, so pasting a link works.

How it talks to the shop

The storefront exposes a GraphQL API that only accepts persisted operations: the operation's hash is part of the URL (/graphql/o/<hash>/<operationName>) and the request body carries variables only. Query text is rejected with a 404, so there is no schema introspection and no arbitrary queries — this server replays the same operations the website itself uses.

The shop is also behind bot protection that rejects plain curl and headless Chromium alike. The persisted endpoints, however, answer ordinary fetch calls, so the running server needs no browser — a browser is only involved when refreshing hashes, below.

Hash rotation: the one thing that will break this

The operation hashes live in src/operations.json. They are tied to the deployed frontend build, so Galaxus rotates them whenever it ships a new frontend — which happens often. When that occurs, the URLs this server calls no longer exist and every tool starts failing at once.

Symptom. Every tool call comes back with:

The persisted hash for "useSearchDataQuery" is no longer accepted by the shop. Galaxus deployed a new frontend and rotated its query hashes. Run npm run refresh-hashes (then npm run build) to re-capture them.

Note the shop reports this in-band: HTTP 200 with the GraphQL error The specified persisted operation key is invalid. — not a 404. So it cannot be mistaken for a network problem.

Checking, without a browser. Because the shop validates the hash before the variables, posting an operation with empty variables tells you whether its hash is alive: a live one complains about a missing variable, a rotated one rejects the key. That is one tiny request per operation:

npm run check-hashes    # exits 0 if all hashes are current, 1 if any rotated

Fixing. Re-capture and rebuild:

npx playwright install chromium   # once, if you have not already
npm run refresh-hashes            # opens a real browser window — let it finish
npm run build
npm run smoke                     # confirm all 7 tools are green again

refresh-hashes drives a real browser across a search page, a category page, a product page and a brand page. It harvests hashes two ways, because neither alone catches everything: from the Relay artifacts embedded in the JS bundles (params:{id:"<hash>",…,name:"<operation>"}) and from the GraphQL requests those pages actually fire. It then rewrites src/operations.json in place, logging every hash that moved, and keeps the previous value (exiting non-zero) for any operation it did not see, rather than writing a broken one.

It runs headed on purpose — headless Chromium gets blocked. Expect a browser window for about a minute; don't close it. Commit the resulting src/operations.json diff.

Automatically. .github/workflows/refresh-hashes.yml runs check-hashes daily. That step needs no browser, so the usual run is cheap and silent. Only when a hash has actually rotated does it install Chromium, re-capture the hashes with a headed browser on a virtual display (xvfb-run, since headless is blocked), re-verify with check-hashes and smoke, and open a PR with the new src/operations.json. You can also trigger it by hand from the Actions tab, with force to re-capture even while the current hashes still work.

One caveat: the workflow talks to Galaxus from a GitHub-hosted runner, and the shop's bot protection judges by IP as well as by browser. If those datacenter IPs turn out to be blocked, the capture step will fail there — run npm run refresh-hashes locally instead (or point the workflow at a self-hosted runner). Nothing else about the server depends on this: it is a maintenance path only.

Two behaviours worth knowing

Search redirects. A generic query like mouse makes the shop return a category redirect instead of products. The server always sends skipRedirect, so you get products back.

The price filter is family-wide. The shop matches a product when any of its variants falls in the price range, while the price it shows is the cheapest variant — so a CHF 100–200 filter would otherwise surface an CHF 82.90 mouse that happens to have a CHF 3860 colourway. The list tools therefore drop products whose own price falls outside min_price/max_price, and page forward to refill the page. Pass strict_price: false to see the shop's raw behaviour.

Scope

Search and discovery only. Anything behind a login — cart, checkout, orders, wishlists, writing reviews — is deliberately out of scope. total_results reflects the shop's own count, which counts product families, so it can exceed the number of rows returned once strict price filtering applies.

Individual review texts are not exposed: the shop renders them server-side and no persisted operation returns them, so galaxus_get_review_summary gives the rating summary and the aggregated pros/cons keywords instead.

Available Tools

7 tools
galaxus_autocompleteAutocomplete a search termA
Read-only

Fast type-ahead lookup. Returns search-term suggestions (with the categories they map to) and a handful of directly matching products. Useful to resolve a vague phrase into a concrete product or category before searching.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesPartial search term.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint true and openWorldHint true, so the description only adds context about returning suggestions and matching products. It does not describe pagination, limits, or other behavioral traits, but the annotation coverage means it doesn't carry the full burden.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the core function, and every sentence contributes value. No filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with annotations and no output schema, the description covers the core behavior and use case. It could mention how to interpret the response or note limitations, but it is sufficient for an agent to decide when to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with 'Partial search term' describing the query parameter. The description adds 'vague phrase' which reinforces the partial nature but doesn't add new syntax or format details beyond schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('type-ahead lookup') and resource ('search-term suggestions' with categories and matching products). It distinguishes itself from sibling tools by focusing on resolving vague phrases before a full search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly mentions when to use: 'Useful to resolve a vague phrase into a concrete product or category before searching.' This gives clear context but does not explicitly list when-not-to-use or name alternatives like galaxus_search, so it misses the top score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

galaxus_browse_brandBrowse a brandA
Read-only

List products from one brand. Brand ids come from the bra facet returned by galaxus_search or galaxus_browse_category.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNoResult ordering.RELEVANCE
limitNoHow many products to return (max 60).
cursorNoPass `next_cursor` from a previous result to page further.
filtersNoFacet constraints, taken from the `filters` block of an earlier result.
brand_idYesNumeric brand id, e.g. 292 for Logitech.
max_priceNoMaximum price in CHF (shorthand for the `pr` range filter).
min_priceNoMinimum price in CHF (shorthand for the `pr` range filter).
strict_priceNoKeep only products whose own price is inside min_price/max_price. The shop matches a product when any of its variants is in range, so turning this off can surface products priced outside the range.

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the agent knows this is a safe read operation. The description adds the useful behavioral detail about brand IDs coming from a facet, but does not disclose other behavioral traits such as pagination behavior or how results are ordered by default. With annotation coverage, this is acceptable but adds only minimal extra context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two short sentences, front-loaded with the main purpose ('List products from one brand') and immediately followed by the most critical usage context. There is no wordiness or repetition; every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having 8 parameters and no output schema, the description is reasonably complete. The schema covers all parameters with descriptions, annotations cover the safety profile, and the description fills the one key gap: where to obtain brand_id. The return format is implied for a list-products tool and not a major omission, so this is adequately complete for the tool's simplicity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents every parameter's meaning and constraints. The description adds a small hint about brand_id ('Brand ids come from the `bra` facet...') but does not enrich the semantics of the other parameters. This matches the baseline of 3 when the schema is self-sufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'List products from one brand.' This uses a specific verb (List) and resource (products) with a clear scope (one brand), distinguishing it from sibling tools like galaxus_browse_category (which lists by category) and galaxus_search (which is broader). It also gives a concrete hint about where to obtain brand IDs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool by explaining that brand IDs come from the `bra` facet of `galaxus_search` or `galaxus_browse_category`. This implicitly indicates a prerequisite workflow. However, it does not explicitly mention alternatives or when not to use it (e.g., 'use search for keyword queries'), so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

galaxus_browse_categoryBrowse a categoryA
Read-only

List products in a category (product type) without a search term — the equivalent of opening a category page. Category ids come from galaxus_search results (category_id), the pt facet, or galaxus_autocomplete.

ParametersJSON Schema
NameRequiredDescriptionDefault
sortNoResult ordering.RELEVANCE
limitNoHow many products to return (max 60).
cursorNoPass `next_cursor` from a previous result to page further.
filtersNoFacet constraints, taken from the `filters` block of an earlier result.
max_priceNoMaximum price in CHF (shorthand for the `pr` range filter).
min_priceNoMinimum price in CHF (shorthand for the `pr` range filter).
category_idYesNumeric product type id, e.g. 62 for Mouse.
strict_priceNoKeep only products whose own price is inside min_price/max_price. The shop matches a product when any of its variants is in range, so turning this off can surface products priced outside the range.

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true and openWorldHint=true, covering safety and variability. The description adds the helpful metaphor 'equivalent of opening a category page' but doesn't disclose additional behavioral traits such as pagination behavior, result limits (though schema covers limit), or any quirks. Given the annotations already handle the key safety signal, a 3 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the core purpose, and every phrase adds value. It avoids redundancy and is appropriately sized for a focused read-only browsing tool. No wasteful fluff or repetition of schema details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 8 parameters and no output schema, so the description could helpfully outline the return shape (products list, next_cursor, filters block). It doesn't, but the schema's filter and cursor parameters imply the response contains those elements. The core action is clear, and the absence of output schema makes the description slightly incomplete but not critically so for a browsing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% description coverage for all 8 parameters, including details on sort enums, cursor semantics, filter structure, and price shorthand. The description itself doesn't add any parameter-specific meaning beyond saying where category_id comes from, which is external context. Baseline 3 applies because the schema carries the burden effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists products in a category without a search term, contrasting with search tools. It specifies the resource (category/product type) and the action (list), and distinguishes from siblings like galaxus_search and galaxus_browse_brand by its unique purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly frames the use case as 'without a search term', implying when to choose category browsing over search. It also tells where category ids come from (search results, pt facet, autocomplete), giving concrete guidance on how to obtain the required parameter. It doesn't explicitly exclude alternatives like browse_brand, but it's clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

galaxus_get_productGet product detailsA
Read-only

Full detail for one product: price and previous price, availability and stock, rating, full specifications, variants, price-history summary, warranty and return policy. Accepts a numeric product id or a Galaxus product URL.

ParametersJSON Schema
NameRequiredDescriptionDefault
productYesNumeric product id (e.g. 61318913) or a full Galaxus product URL.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate read-only and open-world behavior. The description adds transparency by enumerating exactly what data fields will be returned, which goes beyond the annotation hints. There is no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with the primary purpose and then a compact list of included data. No redundant or vague wording.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter read-only tool, the description adequately covers accepted input, the full scope of returned data, and is complete even without an output schema. The annotations further cover safety and open-world aspects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already fully documents the single 'product' parameter with examples of numeric ID and URL formats. The description restates this information without adding new semantic detail, so the baseline score of 3 for high schema coverage applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear, specific action: retrieving full detail for a single product, and enumerates the data included (price, availability, rating, specifications, variants, price history, warranty, returns). It is clearly distinct from sibling search/browse/review tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description makes the intended use obvious—looking up one product by ID or URL—which differentiates it from search/browse siblings, but it does not explicitly state when not to use it or name alternative tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

galaxus_get_review_summarySummarise what reviewers sayA
Read-only

What customers think of a product: the average rating, how many people rated it, and the pros and cons reviewers mention most often. Individual review texts are not exposed by the shop's API.

ParametersJSON Schema
NameRequiredDescriptionDefault
productYesNumeric product id or Galaxus product URL.

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds the behavioral caveat that individual review texts are not available from the API, which is beyond the readOnly/openWorld annotations. It also lists exactly what the summary includes, setting expectations for output granularity. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences with no fluff. The first sentence front-loads the key output details, and the second adds a valuable limitation. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a single-parameter read-only summary tool with no output schema, the description is complete: it explains the input (via schema), the output contents, and a key limitation. An agent has sufficient information to invoke the tool and interpret results.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'product', which is well-defined as 'Numeric product id or Galaxus product URL'. The tool description does not add further detail about this parameter, so it remains at the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: summarizing customer reviews with average rating, rating count, and pros/cons. It distinguishes itself from siblings by focusing on review summaries (e.g., galaxus_get_product likely returns product details). The additional note that individual review texts are not exposed further clarifies its scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool (when a summary of customer sentiment is needed) but does not explicitly state when not to use it or compare with alternatives like galaxus_get_product or galaxus_related_products. The usage guidance is implicit rather than explicit.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 7 tool updatesv0.1.0
    • First observedgalaxus_autocomplete
    • First observedgalaxus_browse_brand
    • First observedgalaxus_browse_category
    • First observedgalaxus_get_product
    • First observedgalaxus_get_review_summary
    • First observedgalaxus_related_products
    • First observedgalaxus_search
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.1/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: autocomplete for suggestions, search for query-based results, get_product for details, browse_category and browse_brand for filtered browsing, related_products for discovery, and review_summary for ratings. There is no overlap; even browse_category and browse_brand are distinguished by their governing attribute (category vs. brand).

Naming Consistency4/5

All tools share the 'galaxus_' prefix, which aids recognition. However, after the prefix the pattern varies: 'search' and 'autocomplete' are bare verbs, 'get_product' and 'get_review_summary' use get_noun, 'browse_category' and 'browse_brand' use verb_noun, while 'related_products' is a noun phrase without a verb. This is a minor deviation that is still predictable and readable.

Tool Count5/5

Seven tools is an ideal size for a product information server—small enough to be easily navigable, yet comprehensive enough to cover search, browsing, retrieval, and related recommendations. Each tool fills a distinct niche without redundancy.

Completeness4/5

The tool set covers the core workflow of product discovery: autocomplete, search, browse by category/brand, full details, related items, and review summaries. A minor gap is that you cannot enumerate all categories or brands independently without first performing a search, but facet-based access is a reasonable design. No dead ends appear for typical shopping research.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • galaxus-mcp

    LeonardoRO
    A
    license
    A
    quality
    B
    maintenance
    Enables AI assistants to search products and retrieve detailed information from Galaxus and Digitec, including prices, specifications, and price history.
    5
    2
    MIT

  • ProductLens-MCP

    KeJ123
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables product comparison and analysis for any MCP-compatible AI assistant, with tools like compare_products and list_products.
    -