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 |
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 |
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-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: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
Metadata
Release files for sahmk-mcp 0.8.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| sahmk_mcp-0.8.1.tar.gz | 24.0 kB | Without provenance | Details for sahmk_mcp-0.8.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| sahmk_mcp-0.8.1-py3-none-any.whl | Python 3 | none | any | Details for sahmk_mcp-0.8.1-py3-none-any.whl |
Total release size: 40.8 kB
Release files / sahmk_mcp-0.8.1.tar.gz
| Download URL | sahmk_mcp-0.8.1.tar.gz |
|---|---|
| Size | 24.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c93ea8c789c0de0b97854b4fefeeb9a3996888af014b46def52705294b392842
|
|
BLAKE2b-256 checksum How to use checksums |
74d553633e9b74a003afc418e985a7f21179b0040c3d13a1aa779c64082aa2a2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / sahmk_mcp-0.8.1-py3-none-any.whl
| Download URL | sahmk_mcp-0.8.1-py3-none-any.whl |
|---|---|
| Size | 16.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8dac0710d40052007f92d2411a324b2e6f02221b809bcd995ad229617cea248c
|
|
BLAKE2b-256 checksum How to use checksums |
5257c2e649c4e395cf932fd6c295bfb9d980cecd9321928fe727a158fd7a0d25
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for sahmk-mcp 0.8.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.