# 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](https://developer.allegro.pl/) 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:

```json
{
  "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 злотых".