1. What is MCP?
MCP (Model Context Protocol) is an open standard that lets AI assistants call external tools. The SAHMK MCP server gives your assistant these tools for Tadawul data:
| Tool | What it does |
|---|---|
| get_quote | Get live quote details for one company identifier |
| get_quotes | Compare live quotes for multiple company identifiers |
| companies_list | Discover symbols with search, market, limit, and offset |
| get_market_summary | See how an index is performing today |
| get_market_movers | Get top gainers, losers, or active stocks with stable type, index, count, and items |
| get_sectors | View sector performance with stable index, count, and items |
| get_company | Get company profile and key fundamentals |
| get_historical | Fetch historical OHLCV price data (1d, 1w, 1m, 30m, 60m; plan/date-window limits apply) |
| get_financials | Review company financial statements and metrics |
| get_dividends | See dividend history and payout details |
Note: get_financials and get_dividends may require an eligible plan (Starter+ or above).
Every path uses your existing SAHMK subscription
ChatGPT, Claude.ai, Claude Desktop, and Cursor use the same SAHMK developer account, the same daily quota, and the permissions already on your plan.
- Plan: the Free, Starter, Pro, Business, or Enterprise plan you already have.
- Permissions: what your API key and plan already allow. Real-time data is available only when your plan includes it.
- Quota: every tool call counts toward your SAHMK daily request limit.
2. Connect SAHMK to ChatGPT
SAHMK is listed in the ChatGPT Plugins Directory. Add it from the public listing.
You need a SAHMK developer account and an API key. Create an account, or open API Keys if you already have one.
Add SAHMK to ChatGPT- Open the SAHMK listing in the ChatGPT Plugins Directory.
- Add or connect SAHMK.
- Sign in to SAHMK.
- Select an API key and allow access. Requests run through that key and your current plan.
- Start a conversation and select @SAHMK.
Example:
ما سعر سهم أرامكو الآن، وما حجم التداول وأفضل سعري طلب وعرض؟
3. Connect SAHMK to Claude
SAHMK is listed in the Claude directory. Add it from the public listing.
You need a SAHMK developer account and an API key. Create an account, or open API Keys if you already have one.
Add SAHMK to Claude- Open the SAHMK listing in the Claude directory.
- Sign in to Claude and add SAHMK.
- Sign in to SAHMK.
- Select an API key and allow access. Requests run through that key and your current plan.
- In a conversation, Claude uses SAHMK tools automatically when they are relevant.
Example:
ما سعر سهم أرامكو الآن، وما حجم التداول وأفضل سعري طلب وعرض؟
4. Local MCP for Claude Desktop and Cursor
Claude Desktop and Cursor run the official SAHMK MCP server locally from PyPI. This path also uses your existing API key and SAHMK subscription; every tool call counts toward the same daily quota.
Get your API key
You need a SAHMK API key. Get your free key by signing up here.
Your key starts with shmk_live_ or shmk_test_.
Installation
Install the MCP server from PyPI:
pip install -U sahmk-mcpIf MCP tools reject newer parameters, upgrade with pip install -U sahmk-mcp and restart your MCP client.
Verify it's installed:
sahmk-mcp --helpConnect to Claude Desktop
Add the following to your Claude Desktop config file.
On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"sahmk": {
"command": "sahmk-mcp",
"env": {
"SAHMK_API_KEY": "your_api_key_here"
}
}
}
}Restart Claude Desktop. You should see the SAHMK tools available in the tools menu.
Connect to Cursor
Add the following to your project's .cursor/mcp.json:
{
"mcpServers": {
"sahmk": {
"command": "sahmk-mcp",
"env": {
"SAHMK_API_KEY": "your_api_key_here"
}
}
}
}Restart Cursor. The SAHMK tools will be available to the AI assistant in your editor.
5. Try it out
After connecting in ChatGPT, Claude, or Cursor, ask questions in plain language. The tools and limits are the same because every path uses your SAHMK subscription.
Quote tools accept identifiers: symbol, Arabic company name, English name, or alias. Symbols are still supported. If a prompt resolves to multiple companies, ask the model to retry with the exact symbol.
For discovery workflows, use companies_list first (supports search, market, limit, and offset).
Prompt
ما سعر سهم أرامكو الآن، وما حجم التداول وأفضل سعري طلب وعرض؟
Asks for Aramco’s price, volume, and best bid and ask.
Prompt
How is the Saudi market doing today?Calls get_market_summary.
Prompt
Show the top gainers in TASICalls get_market_movers.
Prompt
Show sector performance in TASICalls get_sectors.
Prompt
Get financials for AramcoCalls get_financials.
Prompt
Show dividends for AramcoCalls get_dividends.
Prompt
Compare Aramco and Al Rajhi BankCalls get_quotes.
Prompt
Show Aramco's price history for the last 3 monthsCalls get_historical.
Financials and dividends may require an eligible plan (Starter+ or above).
6. Available plans
These limits apply to MCP tool calls in ChatGPT and in local clients alike.
| Plan | Price | Requests/day |
|---|---|---|
| Free | 0 SAR | 100 |
| Starter | 149 SAR/mo | 5,000 |
| Pro | 499 SAR/mo | 50,000 |
| Business | 1,499 SAR/mo | 150,000 |
| Enterprise | Contact us | Custom |
The free plan gives you 100 requests per day — enough to get started and test the integration.
7. Next steps
- →Browse the SAHMK MCP source code on GitHub
- →Explore the Python SDK quick start for building custom applications
- →Check the API reference for all available endpoints
Give your AI assistant access to Tadawul
Add SAHMK from the ChatGPT Plugins Directory or the Claude directory, or install the local server for Claude Desktop and Cursor. 100 free requests per day, no credit card required.