Skip to main content
Glama
sahmk-mcp
by sahmk-sa

SAHMK MCP Server

Official Source

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

get_market_summary

Summary for TASI or NOMU

get_market_movers

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

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.16.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.16.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_trades.events[].side: optional trade side, one of buy, sell, or null.

  • 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)

  • Trades event side is additive and optional: each events[] item may include side = buy, sell, or null.

  • 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.8.1: bump minimum sahmk SDK requirement to 0.16.0.

  • 0.8.0: add optional side to get_trades events (buy/sell/null) with backward-compatible output for payloads that omit it.

  • 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

Available Tools

15 tools
companies_listA

Discover listed companies and symbols. Use this first to find/validate symbols before quote/company calls.

Inputs: limit, market, offset, search. Returns: object

compare_symbolsB

Compare multiple Saudi-listed companies using normalized financial ratios and key metrics. Starter supports up to 3 symbols; Pro supports up to 10.

Inputs: symbols (required), metrics. Returns: object

get_companyA

Get a company profile for a Saudi stock, including sector, industry, fundamentals, valuation, technical indicators, and analyst consensus. Use this when the user asks about a company's profile, key metrics, or detailed information.

Inputs: identifier (required). Returns: object

get_depthA

Get market depth (order book) for a Saudi stock. Use this for bid/ask ladder, spread, imbalance, and liquidity at the top of book. Requires exact exchange symbol. Plan/entitlement-gated by the API.

Inputs: symbol (required), levels. Returns: object

get_dividendsA

Get company dividend history and yield data. Use this when the user asks for dividends or payout history. Requires exact exchange symbol.

Inputs: symbol (required). Returns: object

get_eventsA

Get AI-generated stock event summaries (Pro+ plan). Use this for recent corporate/news-style events with type, importance, and sentiment. Optionally filter by exact exchange symbol.

Inputs: limit, symbol. Returns: object

get_financialsB

Get company financial statements and key financial data. Use this for income statement, balance sheet, and cash flow requests. Requires exact exchange symbol.

Inputs: symbol (required), type, period, result, +4 more. Returns: object

get_historicalA

Get historical OHLCV price data for a Saudi stock over a date range. Use this when the user asks for past prices, price trends, or chart-style historical data.

Inputs: symbol (required), to_date, interval, from_date. Returns: object

get_market_moversA

Get market movers in one curated endpoint. Use this for top gainers, top losers, highest volume leaders, or highest value leaders. Returns a stable schema: type, index, count, items.

Inputs: type (required), index, limit. Returns: object

get_market_summaryA

Get the current Saudi market summary including TASI index level, change, market direction, and advancing/declining stock counts. Use this for questions about the overall market today.

Inputs: index. Returns: object

get_quoteA

Get a real-time quote for a Saudi stock. Use this when the user asks for the current price, change, bid/ask, or trading activity of one stock.

Inputs: symbol, identifier. Returns: object

get_quotesA

Get real-time quotes for multiple Saudi stocks in one call. Use this when the user wants to compare several stocks or asks for prices of more than one symbol.

Inputs: symbols, identifiers. Returns: object

get_ratiosA

Get calculated financial ratios for one Saudi-listed company. Starter returns latest annual core ratios; Pro supports history, quarterly, and extended metrics.

Inputs: symbol (required), period, history, metrics. Returns: object

get_sectorsA

Get sector performance for the Saudi market. Use this when the user asks for sector-level market moves or a sector snapshot. Returns a stable schema: index, count, items.

Inputs: index. Returns: object

get_tradesA

Get recent live trade prints for a Saudi stock (Pro+ plan). Use this for the trade tape: individual executions with price, quantity, value, and a short summary of recent activity. Requires exact exchange symbol.

Inputs: symbol (required), limit. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes, with clear separation between quotes, market-level data, company fundamentals, ratios, and market depth. Minor overlap exists between get_company, get_financials, and get_ratios, but descriptions generally guide selection well.

    Naming Consistency4/5

    The dominant pattern is get_<resource>, which is consistent and predictable. compare_symbols and companies_list break the pattern but are still readable and clear enough to not cause confusion.

    Tool Count5/5

    At 15 tools, the set is well-scoped for a market-data server. Each tool covers a distinct data area such as quotes, movers, sectors, company profiles, financials, depth, trades, and historical data, so every tool earns its place.

    Completeness5/5

    The tool surface is comprehensive for read-only Saudi market data, covering discovery via companies_list, real-time quotes, market summaries, movers, sectors, company details, financials, ratios, dividends, order book depth, trades, events, and historical data. No major dead ends are apparent.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that provides comprehensive financial insights and analysis by leveraging real-time market data, news, and advanced analytics for stocks, options, financial statements, and economic indicators.
      17
      51
      Python
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Official MCP server for EquiVault — AI-powered equity research for Claude. 38 tools covering company fundamentals, financials, ratios, screening, peer comparison, investment narrative, signals intelligence, alerts, briefs, portfolio analytics, insider transactions, and earnings quality. Tier-aware with upgrade prompts. Install: npx equivault-mcp.
      38
      8 npm
      1
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Comprehensive MCP server for real-time stock, cryptocurrency, options, and fundamental analysis, including SEC filings and insider trading data.
      26
      9 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      FinancialFilings gives AI assistants and agents official filings, as published (annual and interim reports, ad-hoc disclosures, insider transactions, ESG reports) and standardized financials for listed companies in the US, EU, UK, APAC and LATAM. Remote MCP server at https://mcp.financialfilings.com/mcp with OAuth sign-in: no API key to copy, free for any FinancialFilings account.
      2
      MIT