Skip to main content
Glama
haraj-mcp

haraj-mcp

by bibo242

haraj-mcp

M8ven Live Monitored

A Model Context Protocol (MCP) server for haraj.com.sa — the largest classified-ads marketplace in Saudi Arabia.

This server exposes 21 tools to any MCP-aware agent (Claude Desktop, Cursor, opencode, Zed, etc.) so it can search and fetch marketplace listings in real time, no copy-paste of curl commands required.

All tools mirror the real haraj.com.sa operations captured from a live browser session (2026-08-17). No hallucinated filters — every argument matches what the live front end actually sends in its GraphQL calls.

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

Tools exposed (21)

Discovery

Tool

Purpose

trending_keywords(range_in_days)

Top trending search terms (default 7 days)

search_suggest(prefix)

Live search-box autocomplete (top 10)

related_tags(tag)

Cities-with-counts for a given tag

live_streams(limit)

Currently-open haraj live shopping streams

Tool

Purpose

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

Tag-based feed (homepage + category pages). before_update_date is the cursor — pass the last item's updateDate to get the next page.

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

Keyword search. during_date accepts 1days/3days/1week/1months. near is a geohash @lat,lon.

promoted_posts(tag)

Promoted-post carousel for a tag

sellers_list(tags, page?)

Sellers per tag (real estate etc.)

Post detail

Tool

Purpose

get_post_details(post_id)

Post + 3 related groups (via the real similarPosts endpoint — canonical "fetch by id")

post_like_info(post_id)

{is_like, total, is_following}

comments(post_id)

Comment list

post_contact(post_id)

{contactText, contactMobile, shouldEnableWhatsApp}

locker_shipment_offer(post_id)

{offerId, isEligible, price} (Locker shipping)

User

Tool

Purpose

user(username?, user_id?, rating_summary_only?)

Full profile (rating, followers, location history, badges)

is_following_user(username)

bool

follow_user(username)

Mutation: toggles follow

user_mention_suggestions()

For @-mentions

Account

Tool

Purpose

notes(set_read?)

Notifications (the bell icon)

outgoing_buy_requests(page?)

"Buy with confidence" escrow history

is_following_tag(tag)

bool

check_auth()

Verify .env credentials are still valid

For fetch_feed, promoted_posts, and search, pass full=True to get the entire Post object instead of a compact summary. The compact summary has these keys:

{
  "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,
  "image_count": 3,
  "thumb_urls": [
    "https://mimg6cdn.haraj.com.sa/.../a.jpg",
    "https://mimg6cdn.haraj.com.sa/.../b.jpg",
    "https://mimg6cdn.haraj.com.sa/.../c.jpg"
  ],
  "tags": ["شاشات", "..."],
  "has_price": true
}

The compact result includes up to 3 image URLs (thumb_urls). Pass any of those URLs to your vision tool to view the post's photos. For posts with more than 3 images, the rest are in the full Post object (full=True) or in get_post_details(post_id) — image_count tells you the total.

Related MCP server: opensooq-mcp

Install

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

This installs the haraj-mcp console script on your PATH.

Configure auth

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

How to get fresh values (they expire every ~10 days):

  1. Open https://haraj.com.sa in Chrome and log in.

  2. F12 → Network tab → click any graphql.haraj.com.sa request.

  3. In Headers, copy authorization (starts with Bearer eyJ…) and lastRequestId.

  4. Paste into .env and restart the MCP server.

You can verify with check_auth — it returns the JWT's exp claim and seconds_remaining.

Wire into your MCP client

opencode / Claude Desktop / Cursor

Add this to your client's MCP config (usually ~/.config/opencode/opencode.json, ~/Library/Application Support/Claude/claude_desktop_config.json, or ~/.cursor/mcp.json):

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

The server reads .env from cwd, so secrets stay in the project directory and don't leak into your MCP client config.

Custom .env location

Set HARAJ_MCP_ENV=/path/to/.env in the env block of the MCP config.

Example agent prompts

Once wired in, your agent can answer:

"What's trending on haraj today?"

"Fetch the latest 20 posts in حراج السيارات (the cars category)."

"Search haraj for RTX 4090 in the last week (during_date=1week)."

"Get the seller's profile and all their current listings for post_id=185354313."

"What shipping fee do I pay if I buy this post via Locker?"

"What are people typing in the search box after شاشة?"

"List all open live shopping streams right now."

Run without an MCP client (debug)

Pipe JSON-RPC messages directly into the 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

12 tests cover: tool registration (21 tools), live version URL, sec-ch-ua-platform-version header, initalChars typo preservation, real search variables, compact serializer shape, JWT validation (valid/expired/malformed), check_auth error handling, a full stdio end-to-end test, tool annotations (all four hints declared as booleans on every tool), and JSON-schema descriptions on every tool parameter.

Agent guide

For a per-tool "what is this used for" reference (and example agent workflows), see docs/AGENT_GUIDE.md. It explains:

  • The 21 tools organized by use case (discovery, feed/search, post detail, user, account)

  • Common multi-step workflows (e.g. "find me a deal on an RTX 4090" → 5 chained tool calls)

  • Pagination cheatsheet (which tools use which cursor)

  • Privacy / safety notes (which tools return sensitive data like IBANs and mobile numbers)

  • Conversation snippets showing the agent calling tools

Share docs/AGENT_GUIDE.md with the LLM client (or use it as a reference when writing system prompts).

Project structure

haraj-mcp/
├── pyproject.toml
├── README.md
├── LICENSE
├── .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

What changed in v0.2.0

v0.1.0 had 4 tools (search_haraj, get_post, list_regions, check_auth) that I had hallucinated from the live GraphQL schema — many of the supported filters were never used by the real site.

v0.2.0 replaces them with 21 tools that mirror the actual operations haraj.com.sa uses. Captured from a real browser session on 2026-08-17 (219 requests, 173 GraphQL POSTs). The key fixes:

  • search no longer has hallucinated filters (carExtraInfo, priceRange, userLocation, notTag, authorUsername); only the variables the live site actually sends (search, cities, city, tag, tags, page, limit, onlyWithImage, onlyWithVideo, hideShowRooms, orderByPostId, duringDate, near)

  • searchSuggest preserves the live wire's typo initalChars (the server requires it)

  • The version URL param bumped to 2026-08-11 22 (was 2026-08-03 15)

  • Added sec-ch-ua-platform-version header (sent on every live call)

  • ViewOptions has mustLoginToView (only present on posts op)

  • New live_streams tool for the non-GraphQL livestream.haraj.com.sa endpoint

  • get_post_details now uses the proper similarPosts(id:) endpoint (not the ID-as-keyword hack)

What changed in v0.3.0

Compact post results now include up to 3 image URLs (thumb_urls) plus an image_count field. The agent can pass any of those URLs to its vision tool to view the post's photos. For posts with more than 3 images, the rest are available via full=True (entire Post object) or get_post_details(post_id). The cap of 3 keeps the listing response small (a typical photo is 200-500 KB; 3 URLs ≈ 1-2 KB of metadata).

What changed in v0.4.0

Every tool now declares all four MCP tool-annotation hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) as explicit booleans, so hosts can reason about and warn on tool behaviour (and OpenAI's directory accepts the server). Read-only tools are marked readOnlyHint=true; notes and follow_user are marked as mutating, and check_auth is marked local-only (openWorldHint=false). Added an MIT LICENSE file.

What changed in v0.5.0

Every tool parameter now carries a human-readable description in its JSON schema (via Annotated[..., Field(description=...)]), taking schema description coverage from 0% to 100% across all 52 parameters. This raises the Glama TDQS score for tools that were previously penalized for bare parameter schemas.

License

MIT — see LICENSE.

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