SAHMK MCP Server

Официальное распространение: только GitHub (sahmk-sa/sahmk-mcp) и PyPI (sahmk-mcp). Не устанавливайте из сторонних форков.

Официальный MCP-сервер SAHMK для SAHMK — используйте данные саудовского рынка внутри ИИ-агентов, таких как Cursor и Claude Desktop.

Этот MCP предоставляет набор инструментов Sahmk для ИИ-агентов, чтобы ассистенты могли запрашивать саудовский рынок на естественном языке.

Инструменты

Related MCP server: equivault-mcp

Контракт с приоритетом идентификатора

• Канонические входные данные для инструментов котировок — identifier и identifiers.

• Устаревшие псевдонимы symbol и symbols по-прежнему принимаются для совместимости.

• Отдавайте предпочтение каноническим ключам в промптах, вызовах инструментов и шаблонах клиентов.

• Разрешение выполняется на стороне бэкенда/SDK (названия, псевдонимы и символы); MCP не ведёт собственную карту символов.

Когда использовать MCP, а когда SDK

• Используйте MCP для интерактивных рабочих процессов агентов в таких инструментах, как Cursor и Claude Desktop.

• Используйте Python SDK для скриптов, автоматизации, дашбордов, оповещений, бэктестов и прикладного кода.

Репозиторий SDK: sahmk-sa/sahmk-python

Получите свой API-ключ

1. Зарегистрируйтесь на sahmk.sa/developers

2. Перейдите в Панель управления → API-ключи → Создать ключ

3. Скопируйте ваш ключ (начинается с shmk_live_ или shmk_test_)

Доступ к глубине рынка

get_depth доступен по подписке. Запросите доступ к реальному времени/глубине на панели разработчика:

Запросить доступ к реальному времени

Требуемые переменные окружения

SAHMK_API_KEY обязателен для всех запусков сервера (Claude Desktop, Cursor и прямое использование CLI).
Установите его в конфигурации env вашего MCP-клиента или экспортируйте перед запуском sahmk-mcp.

Необязательно: SAHMK_BASE_URL переопределяет хост публичного Developer API по умолчанию.

Хост API

Базовый URL REST по умолчанию: https://api.sahmk.sa/api/v1/ (соответствует SDK sahmk версии 0.16.0).
https://app.sahmk.sa/api/v1/ остаётся полностью поддерживаемым совместимым хостом — установите SAHMK_BASE_URL, если он вам нужен:

export SAHMK_BASE_URL="https://app.sahmk.sa/api/v1"

Формы путей не изменились (/api/v1/, /api/v2/, /ws/v1/). Маршруты портала/панели управления (/api/developers/*) остаются на app.sahmk.sa и не используются этим MCP.

Установка

pip install sahmk-mcp

Требуется sahmk>=0.16.0 для совместимости с текущим MCP-SDK (хост по умолчанию api.sahmk.sa, инструменты глубины рынка, живых сделок и событий).

Безопасность

• Устанавливайте API-ключи через переменные окружения (SAHMK_API_KEY).

• Никогда не коммитьте ключи в систему контроля версий и не делитесь ими в логах.

• Немедленно ротируйте раскрытые ключи на панели управления Sahmk.

Конфигурация

Claude Desktop

Добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key"
      }
    }
  }
}

Необязательное переопределение совместимого хоста (те же пути на app.sahmk.sa):

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key",
        "SAHMK_BASE_URL": "https://app.sahmk.sa/api/v1"
      }
    }
  }
}

Cursor

Добавьте в .cursor/mcp.json:

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key"
      }
    }
  }
}

Необязательное переопределение совместимого хоста:

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key",
        "SAHMK_BASE_URL": "https://app.sahmk.sa/api/v1"
      }
    }
  }
}

Запуск напрямую

export SAHMK_API_KEY="your_api_key"
sahmk-mcp

Ограничения входных данных инструментов

• get_market_summary.index: TASI или NOMU (псевдоним NOMUC принимается и нормализуется).

• get_market_movers.type: gainers, losers, volume или value.

• get_market_movers.limit: целое число от 1 до 50.

• get_quote.identifier (предпочтительно): принимает числовой символ, арабское/английское название компании или известный псевдоним.

• get_quote.symbol (устаревший псевдоним): принимается для обратной совместимости.

• get_quotes.identifiers (предпочтительно): максимум 50 идентификаторов на запрос.

• get_quotes.symbols (устаревший псевдоним): принимается для обратной совместимости.

• get_financials.symbol: предпочитает точный биржевой символ; MCP пытается выполнить разрешение идентификатора через SDK для названий/псевдонимов, когда это возможно.

• get_financials.period и get_financials.statement_period: если указаны оба, приоритет имеет period.

• get_financials поддерживает необязательные сквозные параметры: type, period, statement_period, history, metrics, result и include_partial.

• Ответ get_financials ориентирован на блоки отчётности и не включает meta.

• get_ratios.symbol: предпочитает точный биржевой символ; MCP пытается выполнить разрешение идентификатора через SDK для названий/псевдонимов, когда это возможно.

• get_ratios.history: по умолчанию latest.

• get_ratios.period: по умолчанию annual.

• get_ratios.metrics: по умолчанию core.

• compare_symbols.symbols: список символов (предпочтительно) или строка, разделённая запятыми; MCP пытается выполнить разрешение идентификатора через SDK для названий/псевдонимов, когда это возможно.

• compare_symbols.metrics: по умолчанию core.

• get_ratios и compare_symbols включают только минимальный meta: period, metrics, warnings.

• Аналитические инструменты не раскрывают внутренние/бэкенд-поля, такие как applied_profile, plan или диагностику источника.

• get_dividends.symbol: предпочитает точный биржевой символ; MCP пытается выполнить разрешение идентификатора через SDK для названий/псевдонимов, когда это возможно.

• get_depth.symbol: предпочитает точный биржевой символ; MCP пытается выполнить разрешение идентификатора через SDK для названий/псевдонимов, когда это возможно.

• get_depth.levels: необязательное целое число от 1 до 20 (по умолчанию на бэкенде обычно 5; подписка может ограничивать ниже запрошенного).

• get_trades.symbol: предпочитает точный биржевой символ; MCP пытается выполнить разрешение идентификатора через SDK для названий/псевдонимов, когда это возможно.

• get_trades.limit: необязательное целое число от 1 до 200 (по умолчанию на бэкенде обычно 50; сначала новые).

• get_trades.events[].side: необязательная сторона сделки, одна из buy, sell или null.

• get_events.symbol: необязательный фильтр точного биржевого символа; опустите для последних событий по всему рынку.

• get_events.limit: необязательное целое число от 1 до 100.

• get_historical.symbol: предпочитает точный биржевой символ; MCP пытается выполнить разрешение идентификатора через SDK для названий/псевдонимов, когда это возможно.

• companies_list.market: TASI или NOMU (псевдоним NOMUC принимается и нормализуется).

• companies_list.limit: целое число больше 0.

• companies_list.offset: целое число больше или равно 0.

• get_historical.interval: 1d, 1w, 1m, 30m или 60m.

• Неоднозначные идентификаторы вызывают AMBIGUOUS_IDENTIFIER с рекомендациями по повторной попытке и кандидатами, когда они доступны.

• Недействительные идентификаторы и запросы, ограниченные тарифом, возвращают базовую ошибку API.

Примеры вызовов инструментов

• Поиск по каталогу компаний: companies_list(search="aramco")

• Каталог компаний с нормализацией псевдонима рынка: companies_list(search="acwa", market="NOMUC")

• Пагинация каталога компаний: companies_list(search="bank", limit=50, offset=100)

• Предпочтительный вызов одиночной котировки: get_quote(identifier="أرامكو")

• Устаревший вызов одиночной котировки: get_quote(symbol="2222")

• Предпочтительный пакетный вызов котировок: get_quotes(identifiers=["سبكيم", "كيان"])

• Устаревший пакетный вызов котировок: get_quotes(symbols=["2222", "1120"])

• Финансовая отчётность по точному символу: get_financials(symbol="1120")

• Финансовые коэффициенты по умолчанию: get_ratios(symbol="1120")

• Расширенные финансовые коэффициенты: get_ratios(symbol="1120", history="5y", period="quarterly", metrics="extended")

• Сравнение символов по умолчанию: compare_symbols(symbols=["1120", "1180", "1010"])

• Расширенное сравнение символов: compare_symbols(symbols=["1120", "1180", "1010", "2222"], metrics="extended")

• Дивиденды по точному символу: get_dividends(symbol="1120")

• Глубина рынка по точному символу: get_depth(symbol="2222")

• Глубина рынка с уровнями: get_depth(symbol="2222", levels=10)

• Последние сделки по точному символу: get_trades(symbol="2222")

• Последние сделки с лимитом: get_trades(symbol="2222", limit=20)

• Сторона события сделки является дополнительной и необязательной: каждый элемент events[] может включать side = buy, sell или null.

• Последние события рынка: get_events(limit=10)

• События для одного символа: get_events(symbol="1120", limit=5)

• Исторические данные по точному символу: get_historical(symbol="1120", interval="1d")

• Исторические данные с явными аргументами дневного диапазона дат: get_historical(symbol="1120", from_date="2026-01-01", to_date="2026-03-31", interval="1d")

• Внутридневные исторические данные по точному символу (ограничено тарифом по API-ключу): get_historical(symbol="1120", interval="60m")

• Внутридневные исторические данные с явными аргументами диапазона дат: get_historical(symbol="1120", from_date="2026-05-01", to_date="2026-05-31", interval="60m")

Каталог компаний / поиск символов

Сначала используйте companies_list, чтобы уменьшить количество ошибок 404 из-за недействительных символов перед инструментами, работающими только с символами.

1. Найдите кандидатов по названию или фрагменту символа:

   • companies_list(search="aramco")

   • companies_list(search="2222")

2. При желании ограничьте поиск по рынку:

   • companies_list(search="acwa", market="NOMUC") (NOMUC нормализуется в NOMU)

3. Выберите символ из results, затем вызовите:

   • get_quote(identifier="<symbol>")

   • get_financials(symbol="<symbol>")

   • get_dividends(symbol="<symbol>")

   • get_historical(symbol="<symbol>")

4. Для циклов пагинации увеличивайте offset на limit, пока не достигнете total:

   • companies_list(search="bank", limit=100, offset=0)

   • companies_list(search="bank", limit=100, offset=100)

   • продолжайте, пока offset >= total

Примеры рекомендаций MCP

• Пользователь: «سعر الراجحي» -> вызовите get_quote(identifier="الراجحي").

• Уточнение: «قوائم الشركة» -> если предыдущий результат включает resolved_instrument.symbol = "1120", используйте его повторно и вызовите get_financials(symbol="1120").

Примеры промптов

• "Дай мне сводку по TASI и настроение рынка."

• "Дай мне лидеров рынка TASI по росту."

• "Дай мне лидеров рынка NOMU по объёму."

• "Покажи мне производительность секторов."

• "Сравни سابك, سبكيم и 2222 по изменению цены и чистой ликвидности."

• "Покажи сводку по NOMU на сегодня."

• "Получи финансовую отчётность для 2222."

• "Получи дивиденды для 2222."

• "Покажи книгу заявок / глубину рынка для 2222."

• "Покажи последние сделки для 2222."

• "Какие последние события по акциям?"

• "Получи исторические данные за 1 день для 1120 с 2026-01-01 по 2026-03-31."

• "Расскажи о الراجحي и его секторе."

Примечание: get_financials и get_dividends требуют доступа к Sahmk API на тарифе Starter или выше. Если они недоступны для текущего ключа, MCP возвращает соответствующую ошибку API.

Примечание: get_depth ограничен правами доступа — запросить доступ. get_trades и get_events требуют тарифа Pro+. Если они недоступны для текущего ключа, MCP возвращает ошибку API.

Примечание: внутридневные исторические интервалы (30m, 60m) могут быть ограничены тарифным планом. Если они недоступны для текущего ключа, MCP возвращает ошибку API (например, 403 PLAN_LIMIT).

Release Notes

• 0.8.1: повышение минимального требования к SDK sahmk до 0.16.0.

• 0.8.0: добавлено необязательное поле side в события get_trades (buy/sell/null) с обратно совместимым выводом для полезных нагрузок, в которых оно отсутствует.

• 0.7.0: хост публичного Developer API по умолчанию → api.sahmk.sa (требуется sahmk>=0.15.0); app.sahmk.sa по-прежнему поддерживается через SAHMK_BASE_URL.

• 0.6.0: требуется sahmk>=0.14.0; добавлен get_trades для последних живых сделок (Pro+).

• 0.5.1: добавлена документация со ссылкой на запрос прав доступа к рыночной глубине в README.

• 0.5.0: требуется sahmk>=0.13.0; добавлены get_depth (стакан заявок) и get_events (сводки событий на основе ИИ, Pro+).

• 0.4.7: удалён include_quality из публичного контракта инструмента get_financials, нормализованы эквивалентные арабо-индийские/ASCII цифровые вводы перед проверками конфликтов идентификаторов, улучшен UX формы Glama с помощью селекторов с перечислением для стабильных опций коэффициентов/периодов.

• 0.4.6: добавлен запасной вариант поиска идентификатора на основе SDK для get_company и инструментов, работающих с символами (get_financials, get_ratios, compare_symbols, get_dividends, get_historical), когда ввод имени/псевдонима не позволяет выполнить прямой поиск символа.

• 0.4.5: приведение к sahmk>=0.11.0; расширена поддержка get_historical.interval до 30m/60m; документировано поведение ограничения внутридневных данных тарифным планом.

• 0.4.4: документация: уточнены официальные каналы распространения (только GitHub + PyPI)

• 0.4.3: приведение контракта вывода MCP в соответствие: у финансовых данных нет meta; meta аналитики ограничено period, metrics и warnings.

• 0.4.2: добавлен запасной вариант совместимости имён методов SDK для аналитики (get_ratios/ratios, compare_symbols/compare).

• 0.4.1: требуется sahmk>=0.9.1 в зависимостях пакета и проверке версии во время выполнения.

• 0.4.0: добавлены инструменты аналитических коэффициентов и сравнения; улучшены необязательные параметры финансовых данных.

License

MIT — см. LICENSE