allegro-mcp-searcher

MCP server that lets Claude Desktop search products on Allegro.pl.

Flow:

User (any language) -> Claude -> search_allegro tool -> Allegro API (Polish phrase) -> results

Claude is responsible for translating the user's request into Polish before calling the tool — see the tool's docstring in server.py.

Setup

1. Install dependencies (already done into .venv):

   .venv\Scripts\python.exe -m pip install -r requirements.txt
   

2. Create your Allegro app credentials. You already have a Client ID (claude mcp searcher, 0705c183d13445bcaa0ae15d61b4f0b8). You also need its Client Secret, available on the same app page at https://apps.developer.allegro.pl/.

3. Copy .env.example to .env and fill in both values:

   ALLEGRO_CLIENT_ID=0705c183d13445bcaa0ae15d61b4f0b8
   ALLEGRO_CLIENT_SECRET=<your secret>
   

   .env is gitignored — never commit it.

The server authenticates with Allegro using OAuth2 Client Credentials (app-only token), which is sufficient for public offer search — no user login required.

Production app verification

Since 2021, Allegro's GET /offers/listing endpoint only works for verified applications when using Client Credentials — a freshly created app (like claude mcp searcher) will get 403 AccessDenied until Allegro verifies it. To request verification, use the contact form linked from the offers/listing docs or, if you're in the Partnership Program for Sellers, your account manager. There's no self-service toggle for this.

Sandbox (no verification needed, for development)

While waiting for production verification, you can develop/test against Allegro's sandbox, which does not require a verified app. This needs a separate test account and a separate app registration (different Client ID/Secret from your production ones):

1. Create a sandbox account at https://allegro.pl.allegrosandbox.pl
2. Register an app at https://apps.developer.allegro.pl.allegrosandbox.pl to get a sandbox Client ID/Secret
3. In .env, set:

   ALLEGRO_CLIENT_ID=<sandbox client id>
   ALLEGRO_CLIENT_SECRET=<sandbox client secret>
   ALLEGRO_ENV=sandbox
   

Sandbox product data is test data, not the real catalog — it's only useful for verifying the OAuth/search flow works end-to-end. Switch ALLEGRO_ENV back to production (or remove it, since that's the default) once your production app is verified.

Running standalone (sanity check)

.venv\Scripts\python.exe server.py

This starts the MCP server on stdio and waits for a client to connect.

Registering in Claude Desktop

Edit Claude Desktop's config file (%APPDATA%\Claude\claude_desktop_config.json) and add:

{
  "mcpServers": {
    "allegro-searcher": {
      "command": "E:\\projects\\allegro-mcp-searcher\\.venv\\Scripts\\python.exe",
      "args": ["E:\\projects\\allegro-mcp-searcher\\server.py"]
    }
  }
}

Restart Claude Desktop. The search_allegro tool should then be available — try asking "Найди зерновой кофе Lavazza до 60 злотых".