Skip to main content
Glama
haraj-mcp

haraj-mcp

by bibo242

haraj-mcp

一个用于 haraj.com.sa 的 Model Context Protocol (MCP) 服务器 —— 沙特阿拉伯最大的分类广告市场。

该服务器向任何支持 MCP 的智能体(Claude Desktop、Cursor、opencode、Zed 等)公开 21 个工具,因此它可以实时搜索和获取市场列表,无需复制粘贴 curl 命令。

所有工具都镜像了 haraj.com.sa 的真实操作,这些操作是从真实浏览器会话(2026-08-17)中捕获的。没有臆造的过滤器——每个参数都与实际前端在其 GraphQL 调用中发送的内容一致。

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

可用的工具(21)

发现

工具

用途

trending_keywords(range_in_days)

热门搜索词(默认为 7 天)

search_suggest(prefix)

实时搜索框自动补全(前 10 条)

related_tags(tag)

给定标签下的城市及计数

live_streams(limit)

当前开放的 haraj 直播购物流

信息流 / 搜索

工具

用途

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

基于标签的信息流(首页 + 分类页)。before_update_date 是游标——传入最后一项的 updateDate 即可获取下一页。

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

关键词搜索。during_date 接受 1days/3days/1week/1months。near 是一个 geohash @lat,lon。

promoted_posts(tag)

某个标签的推广帖子轮播

sellers_list(tags, page?)

每个标签下的卖家(房地产等)

帖子详情

工具

用途

get_post_details(post_id)

帖子 + 3 个相关分组(通过真实的 similarPosts 端点——规范的“按 id 获取”)

post_like_info(post_id)

{is_like, total, is_following}

comments(post_id)

评论列表

post_contact(post_id)

{contactText, contactMobile, shouldEnableWhatsApp}

locker_shipment_offer(post_id)

{offerId, isEligible, price}(Locker 运输)

用户

工具

用途

user(username?, user_id?, rating_summary_only?)

完整个人资料(评分、关注者、位置历史、徽章)

is_following_user(username)

布尔值

follow_user(username)

变更操作:切换关注状态

user_mention_suggestions()

用于 @ 提及

账户

工具

用途

notes(set_read?)

通知(铃铛图标)

outgoing_buy_requests(page?)

“放心购买”托管历史

is_following_tag(tag)

布尔值

check_auth()

验证 .env 凭据是否仍然有效

对于 fetch_feed、promoted_posts 和 search,传入 full=True 可获得完整的 Post 对象,而不是紧凑摘要。紧凑摘要包含以下键:

{
  "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

安装

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

这会将 haraj-mcp 控制台脚本安装到你的 PATH 中。

配置身份验证

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

如何获取新值(它们大约每 10 天过期):

  1. 在 Chrome 中打开 https://haraj.com.sa 并登录。

  2. F12 → Network 标签页 → 点击任意 graphql.haraj.com.sa 请求。

  3. 在 Headers 中,复制 authorization(以 Bearer eyJ… 开头)和 lastRequestId。

  4. 粘贴到 .env 中,然后重启 MCP 服务器。

你可以使用 check_auth 进行验证——它会返回 JWT 的 exp 声明和 seconds_remaining。

接入你的 MCP 客户端

opencode / Claude Desktop / Cursor

将此添加到你的客户端的 MCP 配置中(通常是 ~/.config/opencode/opencode.json、~/Library/Application Support/Claude/claude_desktop_config.json 或 ~/.cursor/mcp.json):

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

服务器从 cwd 读取 .env,因此密钥保留在项目目录中,不会泄露到你的 MCP 客户端配置中。

自定义 .env 位置

在 MCP 配置的 env 块中设置 HARAJ_MCP_ENV=/path/to/.env。

示例智能体提示

接入后,你的智能体可以回答:

今天 haraj 上有什么热门内容?

获取 حراج السيارات(汽车分类)中最新 20 个帖子。

搜索 haraj 上最近一周(during_date=1week)的 RTX 4090。

获取 post_id=185354313 的卖家个人资料及其所有当前列表。

如果我通过 Locker 购买此帖子,需要支付多少运费?

在搜索框中输入 شاشة 后,人们会输入什么?

列出当前所有开放的直播购物流。

在没有 MCP 客户端的情况下运行(调试)

将 JSON-RPC 消息直接通过管道传入服务器:

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

测试

python tests/test_smoke.py

10 个测试涵盖:工具注册(21 个工具)、实时 version URL、sec-ch-ua-platform-version 头、initalChars 拼写错误的保留、真实搜索变量、紧凑序列化器形状、JWT 验证(有效/过期/格式错误)、check_auth 错误处理,以及完整的 stdio 端到端测试。

智能体指南

有关每个工具“做什么用”的参考(以及示例智能体工作流),请参阅 docs/AGENT_GUIDE.md。其中说明了:

  • 21 个工具按用例组织(发现、信息流/搜索、帖子详情、用户、账户)

  • 常见的多步骤工作流(例如“帮我找一张 RTX 4090 的优惠” → 5 次连续的工具调用)

  • 分页速查表(哪些工具使用哪个游标)

  • 隐私/安全说明(哪些工具会返回敏感数据,如 IBAN 和手机号码)

  • 展示智能体调用工具的对话片段

将 docs/AGENT_GUIDE.md 分享给 LLM 客户端(或在编写系统提示时将其用作参考)。

项目结构

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

v0.2.0 中的更改

v0.1.0 有 4 个工具(search_haraj、get_post、list_regions、check_auth),这些工具是我从实时 GraphQL schema 中臆造出来的——其中许多受支持的过滤器从未被真实网站使用过。

v0.2.0 用 21 个工具 替换了它们,这些工具镜像了 haraj.com.sa 实际使用的操作。这些操作是从 2026-08-17 的真实浏览器会话中捕获的(219 个请求,173 个 GraphQL POST)。主要修复:

  • search 不再包含臆造的过滤器(carExtraInfo、priceRange、userLocation、notTag、authorUsername);只包含真实网站实际发送的变量(search、cities、city、tag、tags、page、limit、onlyWithImage、onlyWithVideo、hideShowRooms、orderByPostId、duringDate、near)

  • searchSuggest 保留了真实线上环境的拼写错误 initalChars(服务器要求如此)

  • version URL 参数已提升至 2026-08-11 22(之前为 2026-08-03 15)

  • 新增 sec-ch-ua-platform-version 头(每次实时调用都会发送)

  • ViewOptions 包含 mustLoginToView(仅存在于 posts 操作中)

  • 新增 live_streams 工具,用于非 GraphQL 的 livestream.haraj.com.sa 端点

  • get_post_details 现在使用正确的 similarPosts(id:) 端点(而不是将 ID 当作关键词的黑客做法)

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