SAHMK MCP Server

Official distribution: GitHub (sahmk-sa/sahmk-mcp) and PyPI (sahmk-mcp) only. Do not install from third-party forks.

Official SAHMK MCP server for SAHMK — use Saudi market data inside AI agents such as Cursor and Claude Desktop.

This MCP exposes a curated set of Sahmk tools for AI agents, so assistants can query the Saudi market in natural language.

Tools

Related MCP server: equivault-mcp

Identifier-First Contract

• Canonical inputs for quote tools are identifier and identifiers.

• Legacy aliases symbol and symbols are still accepted for compatibility.

• Prefer canonical keys in prompts, tool calls, and client templates.

• Resolution is backend/SDK-backed (names, aliases, and symbols); MCP does not maintain its own symbol map.

When to Use MCP vs SDK

• Use MCP for interactive agent workflows in tools like Cursor and Claude Desktop.

• Use the Python SDK for scripts, automation, dashboards, alerts, backtests, and application code.

SDK repo: sahmk-sa/sahmk-python

Get Your API Key

1. Sign up at sahmk.sa/developers

2. Go to Dashboard → API Keys → Create Key

3. Copy your key (starts with shmk_live_ or shmk_test_)

Market Depth Access

get_depth is entitlement-gated. Request realtime/depth access from the developer dashboard:

Request realtime access

Required Environment Variables

SAHMK_API_KEY is required for all server runs (Claude Desktop, Cursor, and direct CLI usage).
Set it in your MCP client env config or export it before running sahmk-mcp.

Optional: SAHMK_BASE_URL overrides the default public Developer API host.

API Host

Default REST base URL is https://api.sahmk.sa/api/v1/ (aligned with sahmk SDK 0.15.0).
https://app.sahmk.sa/api/v1/ remains a fully supported compatibility host — set SAHMK_BASE_URL if you need it:

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

Path shapes are unchanged (/api/v1/, /api/v2/, /ws/v1/). Portal/dashboard routes (/api/developers/*) stay on app.sahmk.sa and are not used by this MCP.

Installation

pip install sahmk-mcp

Requires sahmk>=0.15.0 for current MCP-SDK compatibility (default host api.sahmk.sa, market depth, live trades, and events tools).

Security

• Set API keys via environment variables (SAHMK_API_KEY).

• Never commit keys to source control or share them in logs.

• Rotate exposed keys immediately from your Sahmk dashboard.

Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Optional compatibility host override (same paths on 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

Add to .cursor/mcp.json:

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

Optional compatibility host override:

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

Run Directly

export SAHMK_API_KEY="your_api_key"
sahmk-mcp

Tool Input Constraints

• get_market_summary.index: TASI or NOMU (NOMUC alias is accepted and normalized).

• get_market_movers.type: gainers, losers, volume, or value.

• get_market_movers.limit: integer from 1 to 50.

• get_quote.identifier (preferred): accepts numeric symbol, Arabic/English company name, or known alias.

• get_quote.symbol (legacy alias): accepted for backward compatibility.

• get_quotes.identifiers (preferred): maximum 50 identifiers per request.

• get_quotes.symbols (legacy alias): accepted for backward compatibility.

• get_financials.symbol: prefers exact exchange symbol; MCP attempts SDK-backed identifier resolution for names/aliases when possible.

• get_financials.period and get_financials.statement_period: if both are provided, period takes precedence.

• get_financials supports optional passthrough params: type, period, statement_period, history, metrics, result, and include_partial.

• get_financials response is statement-block focused and does not include meta.

• get_ratios.symbol: prefers exact exchange symbol; MCP attempts SDK-backed identifier resolution for names/aliases when possible.

• get_ratios.history: defaults to latest.

• get_ratios.period: defaults to annual.

• get_ratios.metrics: defaults to core.

• compare_symbols.symbols: list of symbols (preferred) or comma-separated string; MCP attempts SDK-backed identifier resolution for names/aliases when possible.

• compare_symbols.metrics: defaults to core.

• get_ratios and compare_symbols include minimal meta only: period, metrics, warnings.

• Analytics tools do not expose backend/internal fields such as applied_profile, plan, or source diagnostics.

• get_dividends.symbol: prefers exact exchange symbol; MCP attempts SDK-backed identifier resolution for names/aliases when possible.

• get_depth.symbol: prefers exact exchange symbol; MCP attempts SDK-backed identifier resolution for names/aliases when possible.

• get_depth.levels: optional integer from 1 to 20 (backend default is typically 5; entitlement may cap below the request).

• get_trades.symbol: prefers exact exchange symbol; MCP attempts SDK-backed identifier resolution for names/aliases when possible.

• get_trades.limit: optional integer from 1 to 200 (backend default is typically 50; newest first).

• get_events.symbol: optional exact exchange symbol filter; omit for market-wide recent events.

• get_events.limit: optional integer from 1 to 100.

• get_historical.symbol: prefers exact exchange symbol; MCP attempts SDK-backed identifier resolution for names/aliases when possible.

• companies_list.market: TASI or NOMU (NOMUC alias is accepted and normalized).

• companies_list.limit: integer greater than 0.

• companies_list.offset: integer greater than or equal to 0.

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

• Ambiguous identifiers raise AMBIGUOUS_IDENTIFIER with retry guidance and candidates when available.

• Invalid identifiers and plan-gated requests return the underlying API error.

Tool Call Examples

• Company directory search: companies_list(search="aramco")

• Company directory by market alias normalization: companies_list(search="acwa", market="NOMUC")

• Company directory pagination: companies_list(search="bank", limit=50, offset=100)

• Preferred single quote call: get_quote(identifier="أرامكو")

• Legacy single quote call: get_quote(symbol="2222")

• Preferred batch quote call: get_quotes(identifiers=["سبكيم", "كيان"])

• Legacy batch quote call: get_quotes(symbols=["2222", "1120"])

• Financials by exact symbol: get_financials(symbol="1120")

• Financial ratios defaults: get_ratios(symbol="1120")

• Financial ratios advanced: get_ratios(symbol="1120", history="5y", period="quarterly", metrics="extended")

• Compare symbols defaults: compare_symbols(symbols=["1120", "1180", "1010"])

• Compare symbols extended: compare_symbols(symbols=["1120", "1180", "1010", "2222"], metrics="extended")

• Dividends by exact symbol: get_dividends(symbol="1120")

• Market depth by exact symbol: get_depth(symbol="2222")

• Market depth with levels: get_depth(symbol="2222", levels=10)

• Recent trades by exact symbol: get_trades(symbol="2222")

• Recent trades with limit: get_trades(symbol="2222", limit=20)

• Recent market events: get_events(limit=10)

• Events for one symbol: get_events(symbol="1120", limit=5)

• Historical by exact symbol: get_historical(symbol="1120", interval="1d")

• Historical with explicit daily date range args: get_historical(symbol="1120", from_date="2026-01-01", to_date="2026-03-31", interval="1d")

• Intraday historical by exact symbol (plan-gated by API key): get_historical(symbol="1120", interval="60m")

• Intraday historical with explicit date range args: get_historical(symbol="1120", from_date="2026-05-01", to_date="2026-05-31", interval="60m")

Company Directory / Symbol Discovery

Use companies_list first to reduce invalid-symbol 404s before symbol-only tools.

1. Discover candidates by name or symbol fragment:

   • companies_list(search="aramco")

   • companies_list(search="2222")

2. Optionally scope discovery by market:

   • companies_list(search="acwa", market="NOMUC") (NOMUC is normalized to NOMU)

3. Pick a symbol from results, then call:

   • get_quote(identifier="<symbol>")

   • get_financials(symbol="<symbol>")

   • get_dividends(symbol="<symbol>")

   • get_historical(symbol="<symbol>")

4. For pagination loops, increment offset by limit until you reach total:

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

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

   • continue until offset >= total

MCP Guidance Examples

• User: "سعر الراجحي" -> call get_quote(identifier="الراجحي").

• Follow-up: "قوائم الشركة" -> if previous result includes resolved_instrument.symbol = "1120", reuse it and call get_financials(symbol="1120").

Example Prompts

• "Give me a TASI summary and market mood."

• "Give me TASI market movers by gainers."

• "Give me NOMU market movers by value."

• "Show me sector performance."

• "Compare سابك, سبكيم, and 2222 by price change and net liquidity."

• "Show me NOMU summary for today."

• "Get financials for 2222."

• "Get dividends for 2222."

• "Show me the order book / market depth for 2222."

• "Show me the latest trades for 2222."

• "What are the latest stock events?"

• "Get 1d historical data for 1120 from 2026-01-01 to 2026-03-31."

• "Tell me about الراجحي and its sector."

Note: get_financials and get_dividends require Sahmk API access on Starter or higher. If unavailable for the current key, the MCP returns the underlying API error. Note: get_depth is entitlement-gated — request access. get_trades and get_events require Pro+. If unavailable for the current key, the MCP surfaces the API error. Note: intraday historical intervals (30m, 60m) may be plan-gated. If unavailable for the current key, the MCP surfaces the API error (for example 403 PLAN_LIMIT).

Release Notes

• 0.7.0: default public Developer API host → api.sahmk.sa (require sahmk>=0.15.0); app.sahmk.sa still supported via SAHMK_BASE_URL.

• 0.6.0: require sahmk>=0.14.0; add get_trades for recent live trade prints (Pro+).

• 0.5.1: document market-depth entitlement request link in the README.

• 0.5.0: require sahmk>=0.13.0; add get_depth (order-book ladder) and get_events (AI event summaries, Pro+).

• 0.4.7: remove include_quality from public get_financials tool contract, normalize equivalent Arabic-Indic/ASCII digit inputs before identifier conflict checks, and improve Glama form UX with enum selectors for stable ratio/period options.

• 0.4.6: add SDK-backed identifier fallback for get_company and symbol-first tools (get_financials, get_ratios, compare_symbols, get_dividends, get_historical) when name/alias inputs fail direct symbol lookup.

• 0.4.5: align to sahmk>=0.11.0; extend get_historical.interval support to 30m/60m; document intraday plan-gating behavior.

• 0.4.4: docs: clarify official distribution channels (GitHub + PyPI only)

• 0.4.3: Align MCP output contract: no financials meta; analytics meta is limited to period, metrics, and warnings.

• 0.4.2: Add SDK method-name compatibility fallback for analytics (get_ratios/ratios, compare_symbols/compare).

• 0.4.1: Require sahmk>=0.9.1 in package dependency and runtime version guard.

• 0.4.0: Add analytics ratios and compare tools; enhance financials optional parameters.

License

MIT — see LICENSE