SAHMK MCP Server

公式配布: GitHub (sahmk-sa/sahmk-mcp) と PyPI (sahmk-mcp) のみ。サードパーティのフォークからインストールしないでください。

SAHMK 向け公式 SAHMK MCP サーバー — Cursor や Claude Desktop などの AI エージェント内でサウジ市場データを利用できます。

この MCP は、AI エージェント向けに厳選された 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 Keys → Create Key の順に進む

3. キーをコピー（shmk_live_ または shmk_test_ で始まります）

マーケットデプスへのアクセス

get_depth はエンタイトルメント制限があります。デベロッパーダッシュボードからリアルタイム/デプスアクセスをリクエストしてください:

リアルタイムアクセスをリクエスト

必要な環境変数

SAHMK_API_KEY はすべてのサーバー実行（Claude Desktop、Cursor、直接 CLI 使用）に必要です。
MCP クライアントの env 設定で設定するか、sahmk-mcp を実行する前にエクスポートしてください。

オプション: SAHMK_BASE_URL はデフォルトの公開 Developer API ホストを上書きします。

API ホスト

デフォルトの REST ベース URL は https://api.sahmk.sa/api/v1/ です（sahmk SDK 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

現在の MCP-SDK 互換性には sahmk>=0.16.0 が必要です（デフォルトホスト 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)

• 1 つのシンボルのイベント: 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. ページネーションループでは、total に達するまで offset を limit ずつ増やします:

   • 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 の gainers による市場変動銘柄を教えて。」

• 「NOMU の value による市場変動銘柄を教えて。」

• 「セクターのパフォーマンスを見せて。」

• 「سابك、سبكيم、2222 を価格変動と純流動性で比較して。」

• 「今日の NOMU サマリーを見せて。」

• 「2222 の財務諸表を取得して。」

• 「2222 の配当を取得して。」

• 「2222 のオーダーブック / マーケットデプスを見せて。」

• 「2222 の最新の取引を見せて。」

• 「最新の株式イベントは何ですか？」

• 「1120 の 1d 履歴データを 2026-01-01 から 2026-03-31 まで取得して。」

• 「الراجحي とそのセクターについて教えて。」

Note: get_financials と get_dividends は、Starter 以上の Sahmk API アクセスが必要です。現在のキーで利用できない場合、MCP は基盤となる API エラーを返します。

Note: get_depth はエンタイトルメント制限があります — アクセスをリクエスト。get_trades と get_events は Pro+ が必要です。現在のキーで利用できない場合、MCP は API エラーを表示します。

Note: 日中履歴間隔 (30m, 60m) はプラン制限の対象となる場合があります。現在のキーで利用できない場合、MCP は API エラーを表示します (例: 403 PLAN_LIMIT)。

リリースノート

• 0.8.1: sahmk SDK の最小要件を 0.16.0 に引き上げ。

• 0.8.0: get_trades イベントにオプションの side (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 (AI イベントサマリー、Pro+) を追加。

• 0.4.7: 公開 get_financials ツール契約から include_quality を削除。識別子の競合チェックの前に同等のアラビア・インド数字/ASCII 数字入力を正規化。安定した比率/期間オプションを提供する enum セレクターで Glama フォーム UX を改善。

• 0.4.6: 名前/エイリアス入力による直接のシンボル検索が失敗した場合に、get_company およびシンボル優先ツール (get_financials, get_ratios, compare_symbols, get_dividends, get_historical) 向けの SDK ベースの識別子フォールバックを追加。

• 0.4.5: sahmk>=0.11.0 に合わせる。get_historical.interval のサポートを 30m/60m に拡張。日中プラン制限の動作を文書化。

• 0.4.4: ドキュメント: 公式配布チャネルを明確化 (GitHub + PyPI のみ)

• 0.4.3: MCP 出力契約を整合: financials の meta なし。analytics の meta は period, metrics, warnings に限定。

• 0.4.2: アナリティクス向けの SDK メソッド名互換フォールバックを追加 (get_ratios/ratios, compare_symbols/compare)。

• 0.4.1: パッケージ依存関係とランタイムバージョンガードで sahmk>=0.9.1 を要求。

• 0.4.0: アナリティクスの比率と比較ツールを追加。financials のオプションパラメータを拡張。

ライセンス

MIT — LICENSE を参照