SAHMK MCP Server

Distribución oficial: solo GitHub (sahmk-sa/sahmk-mcp) y PyPI (sahmk-mcp). No instale desde forks de terceros.

Servidor MCP oficial de SAHMK para SAHMK — use datos del mercado saudí dentro de agentes de IA como Cursor y Claude Desktop.

Este MCP expone un conjunto seleccionado de herramientas de Sahmk para agentes de IA, de modo que los asistentes puedan consultar el mercado saudí en lenguaje natural.

Herramientas

Related MCP server: equivault-mcp

Contrato de identificador primero

• Las entradas canónicas para las herramientas de cotización son identifier e identifiers.

• Los alias heredados symbol y symbols todavía se aceptan por compatibilidad.

• Prefiera las claves canónicas en prompts, llamadas a herramientas y plantillas de cliente.

• La resolución está respaldada por backend/SDK (nombres, alias y símbolos); el MCP no mantiene su propio mapa de símbolos.

Cuándo usar MCP vs SDK

• Use MCP para flujos de trabajo interactivos de agentes en herramientas como Cursor y Claude Desktop.

• Use el SDK de Python para scripts, automatización, paneles, alertas, backtests y código de aplicación.

Repositorio del SDK: sahmk-sa/sahmk-python

Obtén tu clave de API

1. Regístrate en sahmk.sa/developers

2. Ve a Panel de control → Claves de API → Crear clave

3. Copia tu clave (empieza con shmk_live_ o shmk_test_)

Acceso a la profundidad de mercado

get_depth está restringido por permiso. Solicita acceso en tiempo real/profundidad desde el panel de desarrollador:

Solicitar acceso en tiempo real

Variables de entorno requeridas

SAHMK_API_KEY es obligatoria para todas las ejecuciones del servidor (Claude Desktop, Cursor y uso directo de CLI).
Configúrala en la configuración env de tu cliente MCP o expórtala antes de ejecutar sahmk-mcp.

Opcional: SAHMK_BASE_URL anula el host público predeterminado de la API de desarrollador.

Host de la API

La URL base REST predeterminada es https://api.sahmk.sa/api/v1/ (alineada con el SDK sahmk 0.16.0).
https://app.sahmk.sa/api/v1/ sigue siendo un host de compatibilidad totalmente compatible: establece SAHMK_BASE_URL si lo necesitas:

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

Las formas de las rutas no cambian (/api/v1/, /api/v2/, /ws/v1/). Las rutas del portal/panel (/api/developers/*) permanecen en app.sahmk.sa y este MCP no las utiliza.

Instalación

pip install sahmk-mcp

Requiere sahmk>=0.16.0 para la compatibilidad actual con MCP-SDK (host predeterminado api.sahmk.sa, profundidad de mercado, operaciones en vivo y herramientas de eventos).

Seguridad

• Establece las claves de API mediante variables de entorno (SAHMK_API_KEY).

• Nunca subas claves al control de versiones ni las compartas en registros.

• Rota inmediatamente las claves expuestas desde tu panel de Sahmk.

Configuración

Claude Desktop

Añade a ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Anulación opcional del host de compatibilidad (mismas rutas en 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

Añade a .cursor/mcp.json:

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

Anulación opcional del host de compatibilidad:

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

Ejecutar directamente

export SAHMK_API_KEY="your_api_key"
sahmk-mcp

Restricciones de entrada de las herramientas

• get_market_summary.index: TASI o NOMU (el alias NOMUC se acepta y normaliza).

• get_market_movers.type: gainers, losers, volume o value.

• get_market_movers.limit: entero de 1 a 50.

• get_quote.identifier (preferido): acepta símbolo numérico, nombre de empresa en árabe/inglés o alias conocido.

• get_quote.symbol (alias heredado): aceptado por compatibilidad hacia atrás.

• get_quotes.identifiers (preferido): máximo 50 identificadores por solicitud.

• get_quotes.symbols (alias heredado): aceptado por compatibilidad hacia atrás.

• get_financials.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.

• get_financials.period y get_financials.statement_period: si se proporcionan ambos, period tiene prioridad.

• get_financials admite parámetros de paso opcionales: type, period, statement_period, history, metrics, result e include_partial.

• La respuesta de get_financials se centra en bloques de estados y no incluye meta.

• get_ratios.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.

• get_ratios.history: el valor predeterminado es latest.

• get_ratios.period: el valor predeterminado es annual.

• get_ratios.metrics: el valor predeterminado es core.

• compare_symbols.symbols: lista de símbolos (preferida) o cadena separada por comas; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.

• compare_symbols.metrics: el valor predeterminado es core.

• get_ratios y compare_symbols incluyen solo meta mínimo: period, metrics, warnings.

• Las herramientas de análisis no exponen campos internos/backend como applied_profile, plan o diagnósticos de origen.

• get_dividends.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.

• get_depth.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.

• get_depth.levels: entero opcional de 1 a 20 (el valor predeterminado del backend suele ser 5; el permiso puede limitarlo por debajo de la solicitud).

• get_trades.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.

• get_trades.limit: entero opcional de 1 a 200 (el valor predeterminado del backend suele ser 50; primero los más recientes).

• get_trades.events[].side: lado de la operación opcional, uno de buy, sell o null.

• get_events.symbol: filtro opcional de símbolo exacto de la bolsa; omítelo para eventos recientes de todo el mercado.

• get_events.limit: entero opcional de 1 a 100.

• get_historical.symbol: prefiere el símbolo exacto de la bolsa; el MCP intenta la resolución de identificadores respaldada por SDK para nombres/alias cuando es posible.

• companies_list.market: TASI o NOMU (el alias NOMUC se acepta y normaliza).

• companies_list.limit: entero mayor que 0.

• companies_list.offset: entero mayor o igual que 0.

• get_historical.interval: 1d, 1w, 1m, 30m o 60m.

• Los identificadores ambiguos generan AMBIGUOUS_IDENTIFIER con orientación de reintento y candidatos cuando están disponibles.

• Los identificadores no válidos y las solicitudes restringidas por plan devuelven el error de API subyacente.

Ejemplos de llamadas a herramientas

• Búsqueda en el directorio de empresas: companies_list(search="aramco")

• Directorio de empresas por normalización de alias de mercado: companies_list(search="acwa", market="NOMUC")

• Paginación del directorio de empresas: companies_list(search="bank", limit=50, offset=100)

• Llamada de cotización única preferida: get_quote(identifier="أرامكو")

• Llamada de cotización única heredada: get_quote(symbol="2222")

• Llamada de cotización por lotes preferida: get_quotes(identifiers=["سبكيم", "كيان"])

• Llamada de cotización por lotes heredada: get_quotes(symbols=["2222", "1120"])

• Estados financieros por símbolo exacto: get_financials(symbol="1120")

• Ratios financieros predeterminados: get_ratios(symbol="1120")

• Ratios financieros avanzados: get_ratios(symbol="1120", history="5y", period="quarterly", metrics="extended")

• Comparación de símbolos predeterminada: compare_symbols(symbols=["1120", "1180", "1010"])

• Comparación de símbolos extendida: compare_symbols(symbols=["1120", "1180", "1010", "2222"], metrics="extended")

• Dividendos por símbolo exacto: get_dividends(symbol="1120")

• Profundidad de mercado por símbolo exacto: get_depth(symbol="2222")

• Profundidad de mercado con niveles: get_depth(symbol="2222", levels=10)

• Operaciones recientes por símbolo exacto: get_trades(symbol="2222")

• Operaciones recientes con límite: get_trades(symbol="2222", limit=20)

• El lado del evento de operaciones es aditivo y opcional: cada elemento de events[] puede incluir side = buy, sell o null.

• Eventos de mercado recientes: get_events(limit=10)

• Eventos para un símbolo: get_events(symbol="1120", limit=5)

• Histórico por símbolo exacto: get_historical(symbol="1120", interval="1d")

• Histórico con argumentos explícitos de rango de fechas diario: get_historical(symbol="1120", from_date="2026-01-01", to_date="2026-03-31", interval="1d")

• Histórico intradía por símbolo exacto (restringido por plan según la clave de API): get_historical(symbol="1120", interval="60m")

• Histórico intradía con argumentos explícitos de rango de fechas: get_historical(symbol="1120", from_date="2026-05-01", to_date="2026-05-31", interval="60m")

Directorio de empresas / Descubrimiento de símbolos

Usa companies_list primero para reducir los errores 404 de símbolos no válidos antes de las herramientas que solo usan símbolos.

1. Descubre candidatos por nombre o fragmento de símbolo:

   • companies_list(search="aramco")

   • companies_list(search="2222")

2. Opcionalmente, limita el descubrimiento por mercado:

   • companies_list(search="acwa", market="NOMUC") (NOMUC se normaliza a NOMU)

3. Elige un símbolo de results y luego llama:

   • get_quote(identifier="<symbol>")

   • get_financials(symbol="<symbol>")

   • get_dividends(symbol="<symbol>")

   • get_historical(symbol="<symbol>")

4. Para bucles de paginación, incrementa offset en limit hasta alcanzar total:

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

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

   • continúa hasta que offset >= total

Ejemplos de orientación para MCP

• Usuario: "سعر الراجحي" -> llama a get_quote(identifier="الراجحي").

• Seguimiento: "قوائم الشركة" -> si el resultado anterior incluye resolved_instrument.symbol = "1120", reutilízalo y llama a get_financials(symbol="1120").

Ejemplos de prompts

• "Dame un resumen de TASI y el estado del mercado."

• "Dame los principales movimientos del mercado TASI por ganadores."

• "Dame los principales movimientos del mercado NOMU por valor."

• "Muéstrame el rendimiento sectorial."

• "Compara سابك, سبكيم y 2222 por cambio de precio y liquidez neta."

• "Muéstrame el resumen de NOMU de hoy."

• "Obtén los estados financieros de 2222."

• "Obtén los dividendos de 2222."

• "Muéstrame la cartera de órdenes / profundidad de mercado de 2222."

• "Muéstrame las últimas operaciones de 2222."

• "¿Cuáles son los últimos eventos bursátiles?"

• "Obtén datos históricos de 1d para 1120 desde 2026-01-01 hasta 2026-03-31."

• "Cuéntame sobre الراجحي y su sector."

Nota: get_financials y get_dividends requieren acceso a Sahmk API en el plan Starter o superior. Si no está disponible para la clave actual, el MCP devuelve el error subyacente de la API.

Nota: get_depth está restringido por derechos de acceso — solicitar acceso. get_trades y get_events requieren Pro+. Si no está disponible para la clave actual, el MCP muestra el error de la API.

Nota: los intervalos históricos intradía (30m, 60m) pueden estar limitados por plan. Si no están disponibles para la clave actual, el MCP muestra el error de la API (por ejemplo 403 PLAN_LIMIT).

Notas de la versión

• 0.8.1: aumenta el requisito mínimo del SDK sahmk a 0.16.0.

• 0.8.0: añade side opcional a los eventos de get_trades (buy/sell/null) con salida compatible con versiones anteriores para los payloads que lo omiten.

• 0.7.0: host público predeterminado de la API de desarrolladores → api.sahmk.sa (requiere sahmk>=0.15.0); app.sahmk.sa sigue siendo compatible mediante SAHMK_BASE_URL.

• 0.6.0: requiere sahmk>=0.14.0; añade get_trades para las impresiones recientes de operaciones en vivo (Pro+).

• 0.5.1: documenta el enlace de solicitud de acceso a la profundidad de mercado en el README.

• 0.5.0: requiere sahmk>=0.13.0; añade get_depth (escalera del libro de órdenes) y get_events (resúmenes de eventos con IA, Pro+).

• 0.4.7: elimina include_quality del contrato público de la herramienta get_financials, normaliza las entradas de dígitos arábigo-indios/ASCII equivalentes antes de las comprobaciones de conflicto de identificadores y mejora la UX del formulario de Glama con selectores de enumeración para opciones estables de ratio/período.

• 0.4.6: añade un respaldo de identificador basado en el SDK para get_company y las herramientas que priorizan el símbolo (get_financials, get_ratios, compare_symbols, get_dividends, get_historical) cuando las entradas de nombre/alias fallan en la búsqueda directa de símbolos.

• 0.4.5: alinea con sahmk>=0.11.0; amplía la compatibilidad de get_historical.interval a 30m/60m; documenta el comportamiento de limitación por plan para intradía.

• 0.4.4: documentación: aclara los canales de distribución oficiales (solo GitHub + PyPI)

• 0.4.3: Alinea el contrato de salida del MCP: sin meta en financials; el meta de analytics se limita a period, metrics y warnings.

• 0.4.2: Añade un respaldo de compatibilidad de nombres de métodos del SDK para analytics (get_ratios/ratios, compare_symbols/compare).

• 0.4.1: Requiere sahmk>=0.9.1 en la dependencia del paquete y en la comprobación de versión en tiempo de ejecución.

• 0.4.0: Añade herramientas de ratios y comparación de analytics; mejora los parámetros opcionales de financials.

Licencia

MIT — ver LICENSE