SAHMK MCP Server

官方发行渠道： 仅限 GitHub（sahmk-sa/sahmk-mcp）和 PyPI（sahmk-mcp）。请勿从第三方分支安装。

面向 SAHMK 的官方 SAHMK MCP 服务器——在 Cursor 和 Claude Desktop 等 AI 智能体中使用沙特市场数据。

该 MCP 为 AI 智能体提供一组精选的 Sahmk 工具，使助手能够用自然语言查询沙特市场。

工具

Related MCP server: equivault-mcp

标识符优先约定

• 报价工具的标准输入为 identifier 和 identifiers。

• 为兼容性考虑，仍接受旧版别名 symbol 和 symbols。

• 在提示词、工具调用和客户端模板中优先使用标准键名。

• 标识符解析由后端/SDK 支持（名称、别名和代码）；MCP 不维护自己的代码映射表。

何时使用 MCP 与 SDK

• 在 Cursor 和 Claude Desktop 等工具中，将 MCP 用于交互式智能体工作流。

• 将 Python SDK 用于脚本、自动化、仪表盘、警报、回测和应用程序代码。

SDK 仓库：sahmk-sa/sahmk-python

获取你的 API 密钥

1. 在 sahmk.sa/developers 注册

2. 前往 Dashboard → API Keys → Create Key

3. 复制你的密钥（以 shmk_live_ 或 shmk_test_ 开头）

市场深度访问权限

get_depth 受权限控制。请从开发者仪表盘申请实时/深度访问权限：

申请实时访问权限

必需的环境变量

所有服务器运行（Claude Desktop、Cursor 和直接 CLI 使用）都需要 SAHMK_API_KEY。
在 MCP 客户端的 env 配置中设置它，或在运行 sahmk-mcp 之前导出它。

可选：SAHMK_BASE_URL 可覆盖默认的公共开发者 API 主机。

API 主机

默认 REST 基础 URL 为 https://api.sahmk.sa/api/v1/（与 sahmk SDK 0.16.0 保持一致）。
https://app.sahmk.sa/api/v1/ 仍是完全受支持的兼容主机——如果需要，请设置 SAHMK_BASE_URL：

export SAHMK_BASE_URL="https://app.sahmk.sa/api/v1"

路径结构不变（/api/v1/、/api/v2/、/ws/v1/）。门户/仪表盘路由（/api/developers/*）仍位于 app.sahmk.sa，本 MCP 不使用这些路由。

安装

pip install sahmk-mcp

需要 sahmk>=0.16.0 以保持当前 MCP-SDK 兼容性（默认主机 api.sahmk.sa、市场深度、实时成交和事件工具）。

安全

• 通过环境变量（SAHMK_API_KEY）设置 API 密钥。

• 切勿将密钥提交到源代码管理或在日志中分享。

• 如密钥泄露，请立即从你的 Sahmk 仪表盘轮换密钥。

配置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key"
      }
    }
  }
}

可选的兼容主机覆盖（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

添加到 .cursor/mcp.json：

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key"
      }
    }
  }
}

可选的兼容主机覆盖：

{
  "mcpServers": {
    "sahmk": {
      "command": "sahmk-mcp",
      "env": {
        "SAHMK_API_KEY": "your_api_key",
        "SAHMK_BASE_URL": "https://app.sahmk.sa/api/v1"
      }
    }
  }
}

直接运行

export SAHMK_API_KEY="your_api_key"
sahmk-mcp

工具输入约束

• get_market_summary.index：TASI 或 NOMU（接受 NOMUC 别名并会进行标准化）。

• get_market_movers.type：gainers、losers、volume 或 value。

• get_market_movers.limit：1 到 50 的整数。

• get_quote.identifier （首选）：接受数字代码、阿拉伯语/英语公司名称或已知别名。

• get_quote.symbol （旧版别名）：为向后兼容而接受。

• get_quotes.identifiers （首选）：每个请求最多 50 个标识符。

• get_quotes.symbols （旧版别名）：为向后兼容而接受。

• get_financials.symbol：优先使用精确的交易所代码；MCP 会尽可能尝试通过 SDK 对名称/别名进行标识符解析。

• get_financials.period 和 get_financials.statement_period：如果同时提供，period 优先。

• get_financials 支持可选的透传参数：type、period、statement_period、history、metrics、result 和 include_partial。

• get_financials 响应以报表块为主，不包含 meta。

• get_ratios.symbol：优先使用精确的交易所代码；MCP 会尽可能尝试通过 SDK 对名称/别名进行标识符解析。

• get_ratios.history：默认为 latest。

• get_ratios.period：默认为 annual。

• get_ratios.metrics：默认为 core。

• compare_symbols.symbols：代码列表（首选）或逗号分隔的字符串；MCP 会尽可能尝试通过 SDK 对名称/别名进行标识符解析。

• compare_symbols.metrics：默认为 core。

• get_ratios 和 compare_symbols 仅包含最简 meta：period、metrics、warnings。

• 分析工具不暴露后端/内部字段，如 applied_profile、plan 或来源诊断信息。

• get_dividends.symbol：优先使用精确的交易所代码；MCP 会尽可能尝试通过 SDK 对名称/别名进行标识符解析。

• get_depth.symbol：优先使用精确的交易所代码；MCP 会尽可能尝试通过 SDK 对名称/别名进行标识符解析。

• get_depth.levels：可选的 1 到 20 整数（后端默认通常为 5；权限可能将上限设得低于请求值）。

• get_trades.symbol：优先使用精确的交易所代码；MCP 会尽可能尝试通过 SDK 对名称/别名进行标识符解析。

• get_trades.limit：可选的 1 到 200 整数（后端默认通常为 50；最新的在前）。

• get_trades.events[].side：可选的成交方向，取值为 buy、sell 或 null 之一。

• get_events.symbol：可选的精确交易所代码过滤器；省略则获取全市场近期事件。

• get_events.limit：可选的 1 到 100 整数。

• get_historical.symbol：优先使用精确的交易所代码；MCP 会尽可能尝试通过 SDK 对名称/别名进行标识符解析。

• companies_list.market：TASI 或 NOMU（接受 NOMUC 别名并会进行标准化）。

• companies_list.limit：大于 0 的整数。

• companies_list.offset：大于或等于 0 的整数。

• get_historical.interval：1d、1w、1m、30m 或 60m。

• 存在歧义的标识符会引发 AMBIGUOUS_IDENTIFIER，并在可用时提供重试指引和候选列表。

• 无效标识符和受套餐限制的请求会返回底层 API 错误。

工具调用示例

• 公司目录搜索：companies_list(search="aramco")

• 按市场别名标准化搜索公司目录：companies_list(search="acwa", market="NOMUC")

• 公司目录分页：companies_list(search="bank", limit=50, offset=100)

• 首选单报价调用：get_quote(identifier="أرامكو")

• 旧版单报价调用：get_quote(symbol="2222")

• 首选批量报价调用：get_quotes(identifiers=["سبكيم", "كيان"])

• 旧版批量报价调用：get_quotes(symbols=["2222", "1120"])

• 按精确代码获取财务报表：get_financials(symbol="1120")

• 财务比率默认值：get_ratios(symbol="1120")

• 财务比率高级用法：get_ratios(symbol="1120", history="5y", period="quarterly", metrics="extended")

• 比较代码默认值：compare_symbols(symbols=["1120", "1180", "1010"])

• 比较代码高级用法：compare_symbols(symbols=["1120", "1180", "1010", "2222"], metrics="extended")

• 按精确代码获取股息：get_dividends(symbol="1120")

• 按精确代码获取市场深度：get_depth(symbol="2222")

• 带层级的市场深度：get_depth(symbol="2222", levels=10)

• 按精确代码获取近期成交：get_trades(symbol="2222")

• 带限制的近期成交：get_trades(symbol="2222", limit=20)

• 成交事件方向是附加且可选的：每个 events[] 项可包含 side = buy、sell 或 null。

• 近期市场事件：get_events(limit=10)

• 单个代码的事件：get_events(symbol="1120", limit=5)

• 按精确代码获取历史数据：get_historical(symbol="1120", interval="1d")

• 带显式每日日期范围参数的历史数据：get_historical(symbol="1120", from_date="2026-01-01", to_date="2026-03-31", interval="1d")

• 按精确代码获取日内历史数据（受 API 密钥套餐限制）：get_historical(symbol="1120", interval="60m")

• 带显式日期范围参数的日内历史数据：get_historical(symbol="1120", from_date="2026-05-01", to_date="2026-05-31", interval="60m")

公司目录 / 代码发现

在仅接受代码的工具之前，先使用 companies_list 以减少无效代码导致的 404。

1. 按名称或代码片段发现候选：

   • companies_list(search="aramco")

   • companies_list(search="2222")

2. 可选地按市场限定发现范围：

   • companies_list(search="acwa", market="NOMUC")（NOMUC 会被标准化为 NOMU）

3. 从 results 中选择一个代码，然后调用：

   • get_quote(identifier="<symbol>")

   • get_financials(symbol="<symbol>")

   • get_dividends(symbol="<symbol>")

   • get_historical(symbol="<symbol>")

4. 对于分页循环，按 limit 递增 offset，直到达到 total：

   • companies_list(search="bank", limit=100, offset=0)

   • companies_list(search="bank", limit=100, offset=100)

   • 继续直到 offset >= total

MCP 使用指引示例

• 用户："سعر الراجحي" -> 调用 get_quote(identifier="الراجحي")。

• 追问："قوائم الشركة" -> 如果之前的结果包含 resolved_instrument.symbol = "1120"，请复用它并调用 get_financials(symbol="1120")。

示例提示词

• "给我一份 TASI 摘要和市场情绪。"

• "给我按涨幅排名的 TASI 市场领涨股。"

• "给我按成交额排名的 NOMU 市场领涨/领跌股。"

• "显示板块表现。"

• "按价格变动和净流动性比较 سابك、سبكيم 和 2222。"

• "显示今天的 NOMU 摘要。"

• "获取 2222 的财务报表。"

• "获取 2222 的股息。"

• "显示 2222 的订单簿/市场深度。"

• "显示 2222 的最新成交。"

• "最新的股票事件是什么？"

• "获取 1120 从 2026-01-01 到 2026-03-31 的 1d 历史数据。"

• "告诉我关于 الراجحي 及其板块的信息。"

注意：get_financials 和 get_dividends 需要 Starter 或更高版本的 Sahmk API 访问权限。如果当前密钥不可用，MCP 将返回底层 API 错误。 注意：get_depth 受权限控制 — 申请访问权限。get_trades 和 get_events 需要 Pro+。如果当前密钥不可用，MCP 会显示 API 错误。 注意：日内历史数据间隔（30m、60m）可能受套餐限制。如果当前密钥不可用，MCP 会显示 API 错误（例如 403 PLAN_LIMIT）。

发布说明

• 0.8.1：将最低 sahmk SDK 版本要求提升至 0.16.0。

• 0.8.0：为 get_trades 事件添加可选的 side 字段（buy/sell/null），并为省略该字段的负载提供向后兼容的输出。

• 0.7.0：默认公共开发者 API 主机 → api.sahmk.sa（需要 sahmk>=0.15.0）；仍可通过 SAHMK_BASE_URL 支持 app.sahmk.sa。

• 0.6.0：需要 sahmk>=0.14.0；新增 get_trades 以获取最近的实时成交记录（Pro+）。

• 0.5.1：在 README 中记录市场深度权限申请链接。

• 0.5.0：需要 sahmk>=0.13.0；新增 get_depth（订单簿深度）和 get_events（AI 事件摘要，Pro+）。

• 0.4.7：从公共 get_financials 工具契约中移除 include_quality，在标识符冲突检查前规范化等效的阿拉伯-印度/ASCII 数字输入，并通过枚举选择器改进 Glama 表单用户体验，以提供稳定的比率/期间选项。

• 0.4.6：为 get_company 和符号优先工具（get_financials、get_ratios、compare_symbols、get_dividends、get_historical）添加基于 SDK 的标识符回退，当名称/别名输入无法直接查找符号时使用。

• 0.4.5：对齐到 sahmk>=0.11.0；将 get_historical.interval 的支持扩展到 30m/60m；记录日内套餐限制行为。

• 0.4.4：文档：明确官方分发渠道（仅 GitHub + PyPI）

• 0.4.3：对齐 MCP 输出契约：财务数据无 meta；分析数据的 meta 仅限于 period、metrics 和 warnings。

• 0.4.2：为分析功能添加 SDK 方法名兼容回退（get_ratios/ratios、compare_symbols/compare）。

• 0.4.1：在包依赖和运行时版本检查中要求 sahmk>=0.9.1。

• 0.4.0：添加分析比率和比较工具；增强财务数据的可选参数。

许可证

MIT — 参见 LICENSE