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 はジオハッシュ @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)

bool

follow_user(username)

ミューテーション: フォローを切り替え

user_mention_suggestions()

@メンション用

アカウント

ツール

目的

notes(set_read?)

通知(ベルアイコン)

outgoing_buy_requests(page?)

「Buy with confidence」エスクロー履歴

is_following_tag(tag)

bool

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

サーバーは .env を cwd から読み込むため、シークレットはプロジェクトディレクトリ内に留まり、MCP クライアント設定に漏れません。

カスタム .env の場所

MCP 設定の env ブロックで HARAJ_MCP_ENV=/path/to/.env を設定します。

エージェント向けのプロンプト例

組み込み後、エージェントは次のような質問に答えられます:

「今日の haraj のトレンドは?」

「حراج السيارات (自動車カテゴリ) の最新20件の投稿を取得して。」

「先週の haraj で RTX 4090 を検索して (during_date=1week)。」

「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 には、ライブの GraphQL スキーマから私が捏造した4つのツール(search_haraj、get_post、list_regions、check_auth)がありました。サポートされていたフィルタの多くは実際のサイトでは使われていませんでした。

v0.2.0 では、それらを haraj.com.sa が実際に使用している操作を再現した 21ツール に置き換えました。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 オペレーションにのみ存在)

  • 非GraphQLの livestream.haraj.com.sa エンドポイント用の新しい live_streams ツール

  • 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