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

| Tool | Use it for | |------|------------| | get_quote | Snapshot for one stock identifier (symbol, name, or alias) | | get_quotes | Compare multiple stock identifiers in one call | | companies_list | Company directory/symbol discovery with pagination | | getmarketsummary | Summary for TASI or NOMU | | getmarketmovers | Top movers by gainers, losers, volume, or value | | get_sectors | Sector performance snapshot | | get_company | Company profile and fundamentals | | get_financials | Financial statements (Starter+ plan) | | get_ratios | Calculated financial ratios (Starter/Pro features vary) | | compare_symbols | Multi-symbol normalized ratio/metrics comparison (Starter/Pro limits vary) | | get_dividends | Dividend history and yield data (Starter+ plan) | | get_depth | Order-book depth (bid/ask ladder, spread, imbalance) (entitlement-gated) | | get_trades | Recent live trade prints / tape (Pro+ plan) | | get_events | AI-generated stock event summaries (Pro+ plan) | | get_historical | Historical OHLCV data |

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.

Get Your API Key

• Sign up at sahmk.sa/developers
• Go to Dashboard → API Keys → Create Key
• Copy your key (starts with shmklive or shmktest)

Market Depth Access

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

Request realtime access

Required Environment Variables

SAHMKAPIKEY 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: SAHMKBASEURL 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 SAHMKBASEURL if you need it:

export SAHMKBASEURL="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 (SAHMKAPIKEY).
• 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/claudedesktopconfig.json:

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMKAPIKEY": "yourapikey"
      }
    }
  }
}

Optional compatibility host override (same paths on app.sahmk.sa):

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMKAPIKEY": "yourapikey",
        "SAHMKBASEURL": "https://app.sahmk.sa/api/v1"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMKAPIKEY": "yourapikey"
      }
    }
  }
}

Optional compatibility host override:

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMKAPIKEY": "yourapikey",
        "SAHMKBASEURL": "https://app.sahmk.sa/api/v1"
      }
    }
  }
}

Run Directly

export SAHMKAPIKEY="yourapikey"
sahmk-mcp

Tool Input Constraints

• getmarketsummary.index: TASI or NOMU (NOMUC alias is accepted and normalized).
• getmarketmovers.type: gainers, losers, volume, or value.
• getmarketmovers.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.
• getfinancials.period and getfinancials.statement_period: if both are provided, period takes precedence.
• getfinancials supports optional passthrough params: type, period, statementperiod, 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.
• getratios and comparesymbols 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: gethistorical(symbol="1120", fromdate="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: gethistorical(symbol="1120", fromdate="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.

• Discover candidates by name or symbol fragment:

• Optionally scope discovery by market:

• Pick a symbol from results, then call:

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

MCP Guidance Examples

• User: "سعر الراجحي" -> call get_quote(identifier="الراجحي").
• Follow-up: "قوائم الشركة" -> if previous result includes resolvedinstrument.symbol = "1120", reuse it and call getfinancials(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."