haraj-mcp
haraj-mcp
Сервер Model Context Protocol (MCP) для haraj.com.sa — крупнейшей доски объявлений в Саудовской Аравии.
Этот сервер предоставляет 21 инструмент любому MCP-совместимому агенту (Claude Desktop, Cursor, opencode, Zed и т.д.), позволяя искать и получать объявления с маркетплейса в реальном времени без копирования и вставки 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)
Обнаружение
Tool | Purpose |
| Самые популярные поисковые запросы (по умолчанию за 7 дней) |
| Автодополнение из живого поискового поля (топ-10) |
| Города с количеством объявлений для указанного тега |
| Текущие открытые прямые эфиры покупок haraj |
Лента / поиск
Tool | Purpose |
| Лента на основе тега (главная страница + страницы категорий). |
| Поиск по ключевым словам. |
| Карусель продвигаемых объявлений для тега |
| Продавцы по тегу (недвижимость и т.д.) |
Детали объявления
Tool | Purpose |
| Объявление + 3 связанные группы (через настоящий эндпоинт |
|
|
| Список комментариев |
|
|
|
|
Пользователь
Tool | Purpose |
| Полный профиль (рейтинг, подписчики, история местоположений, значки) |
| bool |
| Мутация: переключает подписку |
| Для @-упоминаний |
Аккаунт
Tool | Purpose |
| Уведомления (значок колокольчика) |
| История эскроу "Покупка с уверенностью" |
| bool |
| Проверка, что учётные данные из |
Для 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 дней):
Откройте https://haraj.com.sa в Chrome и войдите в систему.
F12 → вкладка Network → нажмите на любой запрос к
graphql.haraj.com.sa.В Headers скопируйте
authorization(начинается сBearer eyJ…) иlastRequestId.Вставьте их в
.envи перезапустите MCP-сервер.
Проверить можно с помощью check_auth — он возвращает утверждение exp из JWT и 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
Укажите HARAJ_MCP_ENV=/path/to/.env в блоке env конфигурации MCP.
Примеры промптов для агента
После подключения ваш агент сможет отвечать:
"Что сегодня в тренде на haraj?" "Получи последние 20 объявлений в
حراج السيارات(категория автомобилей)." "Найди на harajRTX 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.py10 тестов покрывают: регистрацию инструментов (21 инструмент), живой URL version, заголовок 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-схемы, — многие из поддерживаемых фильтров никогда не использовались реальным сайтом.
v0.2.0 заменяет их на 21 инструмент, повторяющий реальные операции, которые использует haraj.com.sa. Зафиксировано в реальной браузерной сессии 2026-08-17 (219 запросов, 173 POST-запроса GraphQL). Ключевые исправления:
searchбольше не содержит выдуманных фильтров (carExtraInfo,priceRange,userLocation,notTag,authorUsername); только те переменные, которые реально отправляет живой сайт (search,cities,city,tag,tags,page,limit,onlyWithImage,onlyWithVideo,hideShowRooms,orderByPostId,duringDate,near)searchSuggestсохраняет опечаткуinitalCharsживого API (сервер требует её)Параметр
versionв URL обновлён до2026-08-11 22(было2026-08-03 15)Добавлен заголовок
sec-ch-ua-platform-version(отправляется при каждом живом вызове)ViewOptionsтеперь содержитmustLoginToView(присутствует только в операцииposts)Новый инструмент
live_streamsдля не-GraphQL эндпоинтаlivestream.haraj.com.saget_post_detailsтеперь использует правильный эндпоинтsimilarPosts(id:)(вместо хака с использованием ID в качестве ключевого слова)
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