haraj-mcp

Ein Model Context Protocol (MCP)-Server für haraj.com.sa — den größten Kleinanzeigen-Marktplatz in Saudi-Arabien.

Dieser Server stellt 21 Tools für jeden MCP-fähigen Agenten bereit (Claude Desktop, Cursor, opencode, Zed, usw.), sodass er Marktplatz-Angebote in Echtzeit suchen und abrufen kann, ohne curl-Befehle kopieren und einfügen zu müssen.

Alle Tools spiegeln die echten haraj.com.sa-Operationen wider, die aus einer Live-Browser-Sitzung (2026-08-17) erfasst wurden. Keine erfundenen Filter – jedes Argument entspricht dem, was das Live-Frontend tatsächlich in seinen GraphQL-Aufrufen sendet.

Claude Desktop / Cursor / opencode
        │
        │  MCP (JSON-RPC over stdio)
        ▼
   ┌──────────────┐
   │  haraj-mcp   │ ── HTTPS ──▶  graphql.haraj.com.sa
   │  (Python)    │                + livestream.haraj.com.sa
   └──────────────┘

Bereitgestellte Tools (21)

Entdeckung

Feed / Suche

Beitragsdetails

Benutzer

Konto

Für fetch_feed, promoted_posts und search übergib full=True, um das gesamte Post-Objekt anstelle einer kompakten Zusammenfassung zu erhalten. Die kompakte Zusammenfassung enthält diese Schlüssel:

{
  "id": 185926519,
  "title": "...",
  "price_sar": 650.0,
  "price_display": "650 SAR",
  "url": "https://haraj.com.sa/...",
  "city": "الشرقيه",
  "geo_city": "الدمام",
  "post_date": 1785729404,
  "has_image": true,
  "thumb_url": "https://mimg6cdn.haraj.com.sa/...",
  "tags": ["شاشات", "..."],
  "has_price": true
}

Installation

cd /mnt/W/Desktop/Software/haraj-mcp
pip install -e .

Dadurch wird das Konsolenskript haraj-mcp in deinem PATH installiert.

Authentifizierung konfigurieren

cp .env.example .env
# Edit .env and paste your HARAJ_JWT and LAST_REQUEST_ID.

So erhältst du neue Werte (sie laufen etwa alle ~10 Tage ab):

1. Öffne https://haraj.com.sa in Chrome und melde dich an.

2. F12 → Tab Netzwerk → klicke auf eine beliebige graphql.haraj.com.sa-Anfrage.

3. Kopiere unter Headers den Wert für authorization (beginnt mit Bearer eyJ…) und lastRequestId.

4. Füge beides in .env ein und starte den MCP-Server neu.

Du kannst die Zugangsdaten mit check_auth überprüfen – es gibt den exp-Anspruch des JWT und seconds_remaining zurück.

In deinen MCP-Client einbinden

opencode / Claude Desktop / Cursor

Füge dies zur MCP-Konfiguration deines Clients hinzu (üblicherweise ~/.config/opencode/opencode.json, ~/Library/Application Support/Claude/claude_desktop_config.json oder ~/.cursor/mcp.json):

{
  "mcpServers": {
    "haraj": {
      "command": "haraj-mcp",
      "cwd": "/mnt/W/Desktop/Software/haraj-mcp"
    }
  }
}

Der Server liest .env aus dem cwd, sodass Geheimnisse im Projektverzeichnis bleiben und nicht in die MCP-Client-Konfiguration gelangen.

Benutzerdefinierter .env-Speicherort

Setze HARAJ_MCP_ENV=/path/to/.env im env-Block der MCP-Konfiguration.

Beispiel-Prompts für Agenten

Nach der Einbindung kann dein Agent auf Folgendes antworten:

„Was ist heute auf haraj im Trend?“

„Rufe die neuesten 20 Beiträge in حراج السيارات (der Kategorie Autos) ab.“

„Suche auf haraj nach RTX 4090 in der letzten Woche (during_date=1week).“

„Rufe das Verkäuferprofil und alle aktuellen Angebote des Verkäufers für post_id=185354313 ab.“

„Welche Versandgebühr zahle ich, wenn ich diesen Beitrag über Locker kaufe?“

„Was tippen die Leute nach شاشة in das Suchfeld?“

„Liste alle derzeit laufenden Live-Shopping-Streams auf.“

Ohne MCP-Client ausführen (Debug)

Leite JSON-RPC-Nachrichten direkt in den Server:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"0"}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_regions","arguments":{}}}' | python -m haraj_mcp

Tests

python tests/test_smoke.py

10 Tests decken ab: Tool-Registrierung (21 Tools), Live-version-URL, sec-ch-ua-platform-version-Header, Beibehaltung des Tippfehlers initalChars, reale Suchvariablen, Form der kompakten Serialisierung, JWT-Validierung (gültig/abgelaufen/fehlerhaft), check_auth-Fehlerbehandlung und einen vollständigen stdio-End-to-End-Test.

Agenten-Anleitung

Eine Referenz pro Tool („Wofür wird das verwendet?“) sowie Beispiel-Workflows für Agenten findest du in docs/AGENT_GUIDE.md. Dort wird erklärt:

• Die 21 Tools, nach Anwendungsfall gegliedert (Entdeckung, Feed/Suche, Beitragsdetails, Benutzer, Konto)

• Häufige mehrstufige Workflows (z. B. „finde mir ein Schnäppchen für eine RTX 4090“ → 5 verkettete Tool-Aufrufe)

• Paginierungs-Spickzettel (welche Tools verwenden welchen Cursor)

• Hinweise zu Datenschutz/Sicherheit (welche Tools sensible Daten wie IBANs und Mobilnummern zurückgeben)

• Gesprächsausschnitte, die den Agenten bei Tool-Aufrufen zeigen

Teile docs/AGENT_GUIDE.md mit dem LLM-Client (oder nutze es als Referenz beim Schreiben von System-Prompts).

Projektstruktur

haraj-mcp/
├── pyproject.toml
├── README.md
├── .env.example
├── src/haraj_mcp/
│   ├── __init__.py
│   ├── __main__.py        # entry point: `python -m haraj_mcp`
│   ├── server.py         # FastMCP setup, 21 tool registrations
│   ├── tools.py          # the 21 tool implementations
│   └── auth.py           # .env reader + JWT validation
├── haraj/                # GraphQL client (captured from live haraj.com.sa)
│   ├── client.py
│   ├── models.py
│   ├── queries.py        # 20 exact-captured query strings
│   ├── constants.py
│   ├── auth.py
│   └── images.py
└── tests/test_smoke.py

Was sich in v0.2.0 geändert hat

v0.1.0 hatte 4 Tools (search_haraj, get_post, list_regions, check_auth), die ich aus dem Live-GraphQL-Schema heraus erfunden hatte – viele der unterstützten Filter wurden von der echten Website nie verwendet.

v0.2.0 ersetzt sie durch 21 Tools, die die tatsächlichen Operationen von haraj.com.sa abbilden. Erfasst aus einer echten Browser-Sitzung am 2026-08-17 (219 Anfragen, 173 GraphQL-POSTs). Die wichtigsten Korrekturen:

• search hat keine erfundenen Filter mehr (carExtraInfo, priceRange, userLocation, notTag, authorUsername); nur die Variablen, die die Live-Site tatsächlich sendet (search, cities, city, tag, tags, page, limit, onlyWithImage, onlyWithVideo, hideShowRooms, orderByPostId, duringDate, near)

• searchSuggest bewahrt den Tippfehler initalChars aus dem Live-Protokoll (der Server verlangt ihn)

• Der version-URL-Parameter wurde auf 2026-08-11 22 angehoben (vorher 2026-08-03 15)

• sec-ch-ua-platform-version-Header hinzugefügt (wird bei jedem Live-Aufruf gesendet)

• ViewOptions enthält jetzt mustLoginToView (nur bei der posts-Operation vorhanden)

• Neues Tool live_streams für den Nicht-GraphQL-Endpunkt livestream.haraj.com.sa

• get_post_details verwendet jetzt den korrekten similarPosts(id:)-Endpunkt (nicht den ID-als-Schlüsselwort-Hack)