merka.ch
Sign in
Back to the listings

API

The Merka catalogue is readable through a public API. One address, one verb, JSON-RPC 2.0 in the body: this is the MCP protocol, the one assistants speak. This page shows how to make a request and what comes back.

https://merka.ch/api/mcp

What the API returns, and what it does not

  • Read only. No tool changes anything: not a listing, not an account, not an order.
  • No personal data. Responses carry a listing's title, price, condition, category, town and link. Never a seller's name, address, contact or identifier.
  • No key to request. The API is open, like the pages it describes.

Making a request

The “method” field chooses what happens, “params” carries the tool and its arguments. Copy this straight into a terminal:

curl -s https://merka.ch/api/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"rechercher_annonces",
                 "arguments":{"texte":"livre","limite":2}}}'

The response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [{ "type": "text", "text": "{
      \"resultats\": 1,
      \"annonces\": [{
        \"id\": \"1b69a020-…\",
        \"titre\": \"Livre Statistiques pour l'économie\",
        \"prixChf\": 25,
        \"categorie\": \"Scolaire & études\",
        \"etat\": \"bon\",
        \"ville\": \"Nyon\",
        \"lien\": \"https://merka.ch/annonce/1b69a020-…\"
      }]
    }" }]
  }
}

The tools

The list below is the one returned by the “tools/list” call — same source, so never stale.

rechercher_annonces

Searches second-hand items for sale on Merka (Switzerland). Returns up to 50 results with title, price in CHF, condition, category and link.

Parameters

  • texte · string — Keywords in French, German, Italian or English
  • categorie · string — 61 values (lister_categories)
  • prixMax · number — Maximum item price in CHF
  • limite · number — 1 to 50, default 20

obtenir_annonce

Returns listing details using its identifier.

Parameters

  • id · string, required — Identifier returned by the search

lister_categories

Returns the 61 categories and the number of published listings.

Parameters

No parameters.

The limits

They count per calling address.

  • 120 calls per minute
  • 20'000 calls per day
  • 50 results at most per call

A refusal returns a “Retry-After” header in seconds: wait that long instead of retrying in a loop.

Wider use, a full feed, write access: write to us and we will talk. contact@merka.ch

Adding Merka to Claude

Merka is added as a custom connector. Nothing to install and nothing to grant: the connector reads the public catalogue only. Paste this address, and nothing else:

https://merka.ch/api/mcp
  1. 1Open settings, then “Connectors”.
  2. 2“Add custom connector”.
  3. 3Paste the address above into the field, and nothing else.
  4. 4“Add”. Merka appears in the list, ready to use.

Team and Enterprise plans: an owner adds it first in the organisation settings, then members click “Connect”.

In Claude Code, one line is enough:

claude mcp add --transport http merka https://merka.ch/api/mcp

Adding Merka to ChatGPT

Two routes. The reliable one is the command line: it writes the setting without any menu.

In a terminal:

codex mcp add merka --url https://merka.ch/api/mcp

Through the settings dialog, if you prefer:

https://merka.ch/api/mcp
  1. 1Open the “Connect to a custom MCP” dialog.
  2. 2Name: Merka.
  3. 3Type: “Streamable HTTP”.
  4. 4Paste the address, then save.

Step 3 is the one people miss: the dialog opens on “STDIO”, which launches a program on your own machine. While it stays there, the field wants a command to run and the address has nowhere to go.

This setting lives in a file, on the computer where you make it. So it has to be repeated on each computer, and it does not apply to the phone.

The machine-readable description

Two formats, one contract: both are generated from the same definition, so they cannot drift apart.

  • /api/openapi.json — OpenAPI 3.1 description, for REST tooling and client generators.
  • {"jsonrpc":"2.0","id":1,"method":"tools/list"} — The protocol's native schema, returned by the “tools/list” call.