Connect AI Agents to Tadawul with SAHMK MCP
Give AI assistants like Claude and Cursor direct access to real-time Saudi stock market data. Ask questions in plain language and get live prices, company profiles, and historical data — no application code required.
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 five tools for Tadawul data:
| Tool | What it does |
|---|---|
| get_quote | Real-time price, change, volume, and liquidity for one stock |
| get_quotes | Compare prices for multiple stocks at once |
| get_market_summary | TASI index, advancing/declining counts, market mood |
| get_company | Company profile, fundamentals, valuation, and analyst data |
| get_historical | Historical daily/weekly/monthly OHLCV price data |
2. 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_.
3. Installation
Install the MCP server from PyPI:
pip install sahmk-mcpVerify it's installed:
sahmk-mcp --help4. Connect 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.
5. 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.
6. Try it out
Once connected, ask your AI assistant questions in plain language.
Get a stock price
Prompt
What's the current price of Aramco?The AI calls get_quote with symbol 2222 and responds with something like:
Aramco (2222) is currently trading at 27.60 SAR, up 0.04 (0.15%) today.
Volume: 15.3M shares traded.Compare multiple stocks
Prompt
Compare Aramco and Al Rajhi BankThe AI calls get_quotes with symbols ["2222", "1120"].
Check the market
Prompt
How is the Saudi market doing today?The AI calls get_market_summary and responds with the TASI index level, change, and market mood.
Company research
Prompt
Tell me about STCThe AI calls get_company with symbol 7010.
Historical prices
Prompt
Show me Aramco's price history for the last 3 monthsThe AI calls get_historical with the appropriate date range and returns daily OHLCV data.
7. Available plans
| Plan | Price | Requests/day |
|---|---|---|
| Free | 0 SAR | 100 |
| Starter | 149 SAR/mo | 5,000 |
| Pro | 499 SAR/mo | 50,000 |
| Enterprise | Contact us | Unlimited |
The free plan gives you 100 requests per day — enough to get started and test the integration.
8. 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
Install the SAHMK MCP server and start asking questions about the Saudi stock market in plain language. 100 free requests per day, no credit card required.