Connecting Heurix to Claude Desktop and Cursor with the MCP server

Ask a natural-language question about your catalog directly inside Claude Desktop or Cursor: no API call to write, the agent bridges it. Fifteen minutes to install, tested end to end before publishing.

What you need

Python 3.10 or later on the machine running your agent (your computer, not a server — the MCP server launches locally, on demand), and a Heurix API key.

Step 1 — Download and install

Download the MCP server, unzip it somewhere stable (not a temporary downloads folder), then install the dependencies:

cd heurix-mcp-server
pip3 install -r requirements.txt
which python3

Keep the result of which python3 handy: you'll need it, as a full path, in the next step.

Step 2 — Configure Claude Desktop

Settings → Developer → Edit Config (creates the file if it doesn't exist). On macOS, it lives at ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows, %APPDATA%\Claude\claude_desktop_config.json.

{
  "mcpServers": {
    "heurix": {
      "command": "/usr/bin/python3",
      "args": ["/full/path/to/heurix-mcp-server/server.py"],
      "env": {
        "HEURIX_API_KEY": "hx_your_api_key",
        "HEURIX_API_BASE": "https://api.heurix.fr"
      }
    }
  }
}

The full path to python3 isn't optional: Claude Desktop launches the configuration with a minimal PATH, so a short command that works in your terminal can fail silently here. Same for the path to server.py: full, never relative (no ~).

Restart Claude Desktop entirely (Cmd/Ctrl+Q, not just closing the window).

What about Cursor?

Same configuration structure, in .cursor/mcp.json (at a project's root) or ~/.cursor/mcp.json (global, all projects). Then: Cursor Settings → Tools & MCP, check that "Enable MCP Servers" is on and that heurix shows a connected status. If something's off, the Output → MCP panel shows the server's raw logs, often more informative than the interface itself.

Step 3 — Test it

In a new conversation, with nothing more specified than a catalog name:

I have a Heurix catalog called mycatalog.
Do I have M8 screws in stock, and at what price?

Behind the exchange, the agent calls heurix_search(catalog="mycatalog", query="M8 screw"), which relays to your Heurix API exactly as any curl call would — the response then comes back rephrased in natural language, with your real references and your real prices.

The three available tools

heurix_search (keyword search, typo-tolerant), heurix_browse (products in a category, with sorting — stock, price, popularity...), and heurix_catalog_stats (lists available catalogs and categories — useful as a first call if the agent doesn't yet know your structure). Every search or Browse call consumes the normal quota of the key used, just like a direct API call.

What an agent actually gets from these three tools on a hardware catalog, query by query, is measured in what an AI agent finds, and does not find, in a technical catalog.

Security

Your API key lives only in the MCP client's local configuration file, never sent in the clear in a tool call: the server reads it once at startup and uses it for every call to the Heurix API. Full documentation of the three tools is in the API reference.