Skip to main content
Glama
haraj-mcp

haraj-mcp

by bibo242

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

Tool

Zweck

trending_keywords(range_in_days)

Die meistgesuchten Suchbegriffe (Standard: 7 Tage)

search_suggest(prefix)

Live-Autovervollständigung des Suchfelds (Top 10)

related_tags(tag)

Städte mit Anzahl für ein bestimmtes Schlagwort

live_streams(limit)

Derzeit laufende haraj-Live-Shopping-Streams

Feed / Suche

Tool

Zweck

fetch_feed(tag, city?, cities?, page?, before_update_date?, limit?)

Tag-basierter Feed (Startseite + Kategorieseiten). before_update_date ist der Cursor – übergib das updateDate des letzten Eintrags, um die nächste Seite zu erhalten.

search(keyword, cities?, city?, tag?, tags?, during_date?, near?, ...)

Stichwortsuche. during_date akzeptiert 1days/3days/1week/1months. near ist ein Geohash @lat,lon.

promoted_posts(tag)

Karussell für beworbene Beiträge zu einem Schlagwort

sellers_list(tags, page?)

Verkäufer pro Schlagwort (Immobilien usw.)

Beitragsdetails

Tool

Zweck

get_post_details(post_id)

Beitrag + 3 zusammengehörige Gruppen (über den echten similarPosts-Endpunkt – kanonisches „per ID abrufen“)

post_like_info(post_id)

{is_like, total, is_following}

comments(post_id)

Kommentarliste

post_contact(post_id)

{contactText, contactMobile, shouldEnableWhatsApp}

locker_shipment_offer(post_id)

{offerId, isEligible, price} (Locker-Versand)

Benutzer

Tool

Zweck

user(username?, user_id?, rating_summary_only?)

Vollständiges Profil (Bewertung, Follower, Standortverlauf, Abzeichen)

is_following_user(username)

bool

follow_user(username)

Mutation: schaltet Folgen um

user_mention_suggestions()

Für @-Erwähnungen

Konto

Tool

Zweck

notes(set_read?)

Benachrichtigungen (das Glockensymbol)

outgoing_buy_requests(page?)

Verlauf der „Buy with confidence“-Treuhandgeschäfte

is_following_tag(tag)

bool

check_auth()

Prüft, ob die .env-Zugangsdaten noch gültig sind

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
}

Related MCP server: opensooq-mcp

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)

Available Tools

21 tools
check_authA
Read-onlyIdempotent

Verify the JWT and lastRequestId in .env are still valid. Returns {ok, expires_at, seconds_remaining, user_id} or {ok: false, error} if the JWT is missing or expired.

Inputs: no named parameters.

commentsC
Read-onlyIdempotent

Comment list for a post. Required: post_id. Optional: page, oldest_first (default true).

Inputs: post_id (required), page, oldest_first.

fetch_feedA
Read-onlyIdempotent

Fetch the post feed for a tag (the homepage + category pages). Required: tag (Arabic category name like 'حراج السيارات' or 'حراج الأجهزة'). Optional: city (Arabic region like 'الشرقيه'), cities (list of regions), page (default 0), limit (default 21), before_update_date (Unix seconds cursor — pass the last item's updateDate to get the next page), only_with_image (default true), only_with_video (default false), order_main_by_post_id (default false), full (return full Post objects, default false = compact). Returns {count, has_next_page, view_options, posts}.

Inputs: tag (required), city, full, page, +6 more.

follow_userA

Follow (or unfollow) a user. Required: username. Returns the new is_following state.

Inputs: username (required).

get_post_detailsA
Read-onlyIdempotent

Fetch a post + 3 related groups (similar posts in the same tag/city, similar images, related offers). This is the canonical 'fetch by id' — there is no direct getById operation in the GraphQL API. Required: post_id. full (default true = full similarPosts response).

Inputs: post_id (required), full.

is_following_tagA
Read-onlyIdempotent

True/false whether the authenticated user follows tag.

Inputs: tag (required), city.

is_following_userB
Read-onlyIdempotent

True/false whether the authenticated user follows username.

Inputs: username (required).

live_streamsB
Read-onlyIdempotent

Currently-open haraj live shopping streams. Non-GraphQL REST endpoint. Returns [{id, title, cover_url, streamer, num_messages, num_viewers, started_at}]. limit (default 40; the server caps it).

Inputs: limit.

locker_shipment_offerC
Read-onlyIdempotent

{offerId, isEligible, price} for a post's Locker shipping option. Required: post_id.

Inputs: post_id (required).

notesB
Idempotent

User notifications (the bell icon). set_read (default false) marks them as read on the server.

Inputs: set_read.

outgoing_buy_requestsB
Read-onlyIdempotent

'Buy with confidence' (وساطة) escrow requests the user has placed. Optional: page (default 0).

Inputs: page.

post_contactC
Read-onlyIdempotent

{contactText, contactMobile, shouldEnableWhatsApp} for a post. Required: post_id.

Inputs: post_id (required).

post_like_infoC
Read-onlyIdempotent

{is_like, total, is_following} for a post. Required: post_id.

Inputs: post_id (required).

search_suggestA
Read-onlyIdempotent

Live search-box autocomplete. Returns the top 10 suggestions for a typed prefix. Required: prefix (e.g. 'شاشة'). Optional: tag.

Inputs: prefix (required), tag.

sellers_listC
Read-onlyIdempotent

Sellers for a tag (used by real-estate / business / investment pages). Required: tags (list of Arabic tag names).

Inputs: tags (required), page.

userA
Read-onlyIdempotent

Full user profile (rating, followers, location history, badges). Pass either username (URL-encoded Arabic works) or user_id. rating_summary_only (default false) returns just the rating block.

Inputs: user_id, username, rating_summary_only.

user_mention_suggestionsA
Read-onlyIdempotent

Recent @-mention candidates for the comment / DM composer. Returns [{userId, username, handler}].

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool targets a clearly distinct resource or action. While several tools return posts (fetch_feed, search, promoted_posts) or relate to users (follow_user, is_following_user, user), the descriptions precisely differentiate their scopes and use cases.

    Naming Consistency3/5

    All names use snake_case, which is consistent, but the grammatical pattern is mixed: some are verb_noun (fetch_feed, get_post_details), some are noun phrases (promoted_posts, post_like_info), and some are is_* predicates (is_following_tag). This inconsistency makes the set less predictable.

    Tool Count3/5

    21 tools is on the high side for a single server, falling into the borderline heavy range per the rubric. Although each tool appears to cover a distinct API feature, the sheer number increases cognitive load and could be consolidated.

    Completeness3/5

    The surface covers many read operations and a few write actions (follow_user, notes set_read), but notable write operations are missing: creating or editing posts, liking/unliking, posting comments, following/unfollowing tags, and sending messages. These gaps limit agent autonomy for core marketplace interactions.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Hosted MCP server for 3926 structured public web-data tools across 488 platform groups, returning clean JSON for search, maps, commerce, social, and finance.
      14
      500
      252 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A read-only MCP server that gives LLM agents live access to OpenSooq, the largest classifieds marketplace in Kuwait, enabling search, pricing, seller reputation, and deal finding.
      2
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Remote MCP server for Saudi real estate data from Kite (kite.sa): live rent and sale listings from 20+ Saudi sources, price checks against comparable listings, neighborhood stats, rental yield and development projects. Connect at https://mcp.kite.sa/mcp with OAuth sign-in.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for the OLX.ba API that enables searching, publishing, editing, and managing listings (ads), including image handling, sponsorships, categories, locations, and user account operations through 36 tools covering all official API endpoints.
      10 npm
      8
      MIT