haraj-mcp

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

Feed / search

Post detail

User

Account

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,
  "thumb_url": "https://mimg6cdn.haraj.com.sa/...",
  "tags": ["شاشات", "..."],
  "has_price": true
}

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

10 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, and a full stdio end-to-end test.

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
├── .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)