sahmk-mcp
This MCP server provides tools to access and analyze Saudi stock market (Tadawul/TASI and NOMU) data, enabling AI agents to query real-time and historical market information.
Real-time stock quotes: Retrieve a snapshot for one (
get_quote) or multiple stocks up to 50 (get_quotes) using symbols, Arabic/English names, or aliases.Market summary (
get_market_summary): Get the current index level, change, direction, and advancing/declining counts for TASI or NOMU.Market movers (
get_market_movers): View top gainers, losers, volume leaders, or value leaders (up to 50 results).Sector performance (
get_sectors): View a performance snapshot across all market sectors.Company profile (
get_company): Access a company's profile, sector, industry, fundamentals, valuation, technical indicators, and analyst consensus.Financial statements (
get_financials): Retrieve income statement, balance sheet, and cash flow data (Starter+ plan required).Financial ratios (
get_ratios): Get calculated financial ratios; extended history and metrics available on Pro.Compare companies (
compare_symbols): Normalize and compare financial ratios/metrics across multiple companies (up to 3 on Starter, up to 10 on Pro).Dividend history (
get_dividends): Retrieve dividend history and yield data (Starter+ plan required).Historical OHLCV data (
get_historical): Fetch price data with daily, weekly, monthly, or intraday (30m/60m) intervals.Company discovery (
companies_list): Search and paginate the company directory by name, symbol, or market to find and validate symbols.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sahmk-mcp what's the current price of Saudi Aramco?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Snapshot for one stock identifier (symbol, name, or alias) |
| Compare multiple stock identifiers in one call |
| Company directory/symbol discovery with pagination |
| Summary for |
| Top movers by |
| Sector performance snapshot |
| Company profile and fundamentals |
| Financial statements (Starter+ plan) |
| Calculated financial ratios (Starter/Pro features vary) |
| Multi-symbol normalized ratio/metrics comparison (Starter/Pro limits vary) |
| Dividend history and yield data (Starter+ plan) |
| Order-book depth (bid/ask ladder, spread, imbalance) (entitlement-gated) |
| Recent live trade prints / tape (Pro+ plan) |
| AI-generated stock event summaries (Pro+ plan) |
| Historical OHLCV data |
Related MCP server: equivault-mcp
Identifier-First Contract
Canonical inputs for quote tools are
identifierandidentifiers.Legacy aliases
symbolandsymbolsare 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
Sign up at sahmk.sa/developers
Go to Dashboard → API Keys → Create Key
Copy your key (starts with
shmk_live_orshmk_test_)
Market Depth Access
get_depth is entitlement-gated. Request realtime/depth access from the developer dashboard:
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-mcpRequires 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-mcpTool Input Constraints
get_market_summary.index:TASIorNOMU(NOMUCalias is accepted and normalized).get_market_movers.type:gainers,losers,volume, orvalue.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.periodandget_financials.statement_period: if both are provided,periodtakes precedence.get_financialssupports optional passthrough params:type,period,statement_period,history,metrics,result, andinclude_partial.get_financialsresponse is statement-block focused and does not includemeta.get_ratios.symbol: prefers exact exchange symbol; MCP attempts SDK-backed identifier resolution for names/aliases when possible.get_ratios.history: defaults tolatest.get_ratios.period: defaults toannual.get_ratios.metrics: defaults tocore.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 tocore.get_ratiosandcompare_symbolsinclude minimalmetaonly: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 ofbuy,sell, ornull.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:TASIorNOMU(NOMUCalias 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, or60m.Ambiguous identifiers raise
AMBIGUOUS_IDENTIFIERwith 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 includeside=buy,sell, ornull.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.
Discover candidates by name or symbol fragment:
companies_list(search="aramco")companies_list(search="2222")
Optionally scope discovery by market:
companies_list(search="acwa", market="NOMUC")(NOMUCis normalized toNOMU)
Pick a symbol from
results, then call:get_quote(identifier="<symbol>")get_financials(symbol="<symbol>")get_dividends(symbol="<symbol>")get_historical(symbol="<symbol>")
For pagination loops, increment
offsetbylimituntil you reachtotal: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 callget_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 minimumsahmkSDK requirement to0.16.0.0.8.0: add optionalsidetoget_tradesevents (buy/sell/null) with backward-compatible output for payloads that omit it.0.7.0: default public Developer API host →api.sahmk.sa(requiresahmk>=0.15.0);app.sahmk.sastill supported viaSAHMK_BASE_URL.0.6.0: requiresahmk>=0.14.0; addget_tradesfor recent live trade prints (Pro+).0.5.1: document market-depth entitlement request link in the README.0.5.0: requiresahmk>=0.13.0; addget_depth(order-book ladder) andget_events(AI event summaries, Pro+).0.4.7: removeinclude_qualityfrom publicget_financialstool 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 forget_companyand 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 tosahmk>=0.11.0; extendget_historical.intervalsupport to30m/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 financialsmeta; analyticsmetais limited toperiod,metrics, andwarnings.0.4.2: Add SDK method-name compatibility fallback for analytics (get_ratios/ratios,compare_symbols/compare).0.4.1: Requiresahmk>=0.9.1in 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 toolscompanies_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
Scored across 15 tools
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.
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.
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.
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
Related MCP Connectors
Official Intrinio MCP server. US stock prices, options and fundamentals for AI agents.
Official MCP server for subfeed.app — the cloud for agents. 15+ tools for AI agents to register, build, and deploy other agents. Zero human required. Start here: subfeed.app/skill.md
Official CoinMarketCap MCP server: real-time crypto prices, market cap, rankings and exchange data.
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Related MCP Servers
- AlicenseBqualityDmaintenanceAn 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.1751PythonMIT

equivault-mcpofficial
AlicenseBqualityDmaintenanceOfficial 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.388 npm1MIT- AlicenseAqualityCmaintenanceComprehensive MCP server for real-time stock, cryptocurrency, options, and fundamental analysis, including SEC filings and insider trading data.269 npmMIT
- AlicenseNot gradedqualityBmaintenanceFinancialFilings 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.2MIT