haraj-mcp
haraj-mcp is an MCP server that gives any MCP-aware agent 21 tools for searching, browsing, and inspecting listings on haraj.com.sa (Saudi Arabia's largest classifieds marketplace) in real time.
Discovery —
trending_keywords(top searches),search_suggest(search-box autocomplete),related_tags(cities-with-counts for a tag),live_streams(open live shopping streams).Feed / search —
fetch_feed(tag-based homepage/category feeds withbefore_update_datecursor pagination),search(keyword search with city/tag/date filters, geohashnear, image/video-only),promoted_posts(promoted carousel),sellers_list(sellers per tag).Post detail —
get_post_details(post + similar posts/images/offers, the canonical fetch-by-id),post_like_info(likes/follow state),comments,post_contact(contact text + mobile + WhatsApp flag),locker_shipment_offer(Locker shipping eligibility/price).User —
user(full profile: rating, followers, badges, location history),is_following_user,follow_user(mutation, toggles follow),user_mention_suggestions.Account —
notes(notifications, optionally mark read),outgoing_buy_requests(escrow history),is_following_tag,check_auth(validate.envJWT/lastRequestId and report expiry).Result shaping — feed/search/promoted tools default to a compact post summary (
id,title,price_sar,url,city, up to 3thumb_urls,image_count, tags) and acceptfull=Truefor the entire Post object; thumb URLs can be passed to a vision tool to view photos.Practical use — supports multi-step agent workflows such as "find an RTX 4090 deal" (search → detail → seller → contact → shipping) and answers natural-language questions about live marketplace listings, trending terms, and sellers. Uses authenticated haraj GraphQL + livestream endpoints, with tools annotated for read-only/mutating behaviour.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@haraj-mcp what's trending on haraj today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Tool | Purpose |
| Top trending search terms (default 7 days) |
| Live search-box autocomplete (top 10) |
| Cities-with-counts for a given tag |
| Currently-open haraj live shopping streams |
Feed / search
Tool | Purpose |
| Tag-based feed (homepage + category pages). |
| Keyword search. |
| Promoted-post carousel for a tag |
| Sellers per tag (real estate etc.) |
Post detail
Tool | Purpose |
| Post + 3 related groups (via the real |
|
|
| Comment list |
|
|
|
|
User
Tool | Purpose |
| Full profile (rating, followers, location history, badges) |
| bool |
| Mutation: toggles follow |
| For @-mentions |
Account
Tool | Purpose |
| Notifications (the bell icon) |
| "Buy with confidence" escrow history |
| bool |
| Verify |
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):
Open https://haraj.com.sa in Chrome and log in.
F12 → Network tab → click any
graphql.haraj.com.sarequest.In Headers, copy
authorization(starts withBearer eyJ…) andlastRequestId.Paste into
.envand 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 4090in 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_mcpTests
python tests/test_smoke.py12 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.pyWhat 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:
searchno 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)searchSuggestpreserves the live wire's typoinitalChars(the server requires it)The
versionURL param bumped to2026-08-11 22(was2026-08-03 15)Added
sec-ch-ua-platform-versionheader (sent on every live call)ViewOptionshasmustLoginToView(only present onpostsop)New
live_streamstool for the non-GraphQLlivestream.haraj.com.saendpointget_post_detailsnow uses the propersimilarPosts(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 toolscheck_authARead-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.
commentsCRead-onlyIdempotent
Comment list for a post. Required: post_id. Optional: page, oldest_first (default true).
Inputs: post_id (required), page, oldest_first.
fetch_feedARead-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_detailsARead-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_tagARead-onlyIdempotent
True/false whether the authenticated user follows tag.
Inputs: tag (required), city.
is_following_userBRead-onlyIdempotent
True/false whether the authenticated user follows username.
Inputs: username (required).
live_streamsBRead-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_offerCRead-onlyIdempotent
{offerId, isEligible, price} for a post's Locker shipping option. Required: post_id.
Inputs: post_id (required).
notesBIdempotent
User notifications (the bell icon). set_read (default false) marks them as read on the server.
Inputs: set_read.
outgoing_buy_requestsBRead-onlyIdempotent
'Buy with confidence' (وساطة) escrow requests the user has placed. Optional: page (default 0).
Inputs: page.
post_contactCRead-onlyIdempotent
{contactText, contactMobile, shouldEnableWhatsApp} for a post. Required: post_id.
Inputs: post_id (required).
post_like_infoCRead-onlyIdempotent
{is_like, total, is_following} for a post. Required: post_id.
Inputs: post_id (required).
promoted_postsBRead-onlyIdempotent
Fetch the promoted-post carousel for a tag. Required: tag. Optional: city. Returns {count, posts}.
Inputs: tag (required), city, full.
searchARead-onlyIdempotent
Search haraj by keyword. Required: keyword. Optional: cities (list), city, tag, tags (list), page, limit, only_with_image (default true), only_with_video (default false), hide_show_rooms (default false), order_by_post_id (default false), during_date ('1days'|'3days'|'1week'|'1months'), near ('@lat,lon' e.g. '@26.4336,50.1116'), full (default false = compact). Returns {keyword, count, has_next_page, view_options, posts}.
Inputs: keyword (required), tag, city, full, +10 more.
search_suggestARead-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_listCRead-onlyIdempotent
Sellers for a tag (used by real-estate / business / investment pages). Required: tags (list of Arabic tag names).
Inputs: tags (required), page.
trending_keywordsBRead-onlyIdempotent
Top trending search terms over the last N days. range_in_days (default 7). Returns [{keyword, score}].
Inputs: range_in_days.
userARead-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_suggestionsARead-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
Scored across 21 tools
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.
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.
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.
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
Related MCP Connectors
All HasData scraping tools in one MCP server: Google, TikTok, Instagram, maps, e-commerce and more.
Hosted MCP server for DataLikers — Instagram & TikTok data API. 51 tools: Instagram user search by demographics (gender/age/race/country/city), profiles, bulk lookup, engagement, posts & reels, comments, hashtags, locations, stories, highlights, music, business accounts, top users; TikTok users, videos, comments, hashtags, playlists and top charts. Streamable HTTP, Bearer API key. Free tier: 100 requests on signup at https://datalikers.com/p/1by27bwg
17 data tools in one MCP server, run on Apify: Google Shopping, Flights, Hotels, News, Images, Videos, Ads Transparency, Jobs and Trends; YouTube transcripts; AI visibility checks; Google Maps leads; App Store and Google Play reviews. Pay per result. Sign in with Apify (OAuth) or an API token.
One MCP server for 180+ live web-data APIs returning clean JSON from sites that block scrapers.
Related MCP Servers
AlicenseCqualityBmaintenanceHosted MCP server for 3926 structured public web-data tools across 488 platform groups, returning clean JSON for search, maps, commerce, social, and finance.14500252 npm1MIT- AlicenseNot gradedqualityDmaintenanceA 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.2MIT
- FlicenseNot gradedqualityBmaintenanceRemote 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-
- AlicenseNot gradedqualityCmaintenanceMCP 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 npm8MIT