SAHMK MCP 서버

공식 배포: 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 vs SDK 사용 시점

• MCP는 Cursor 및 Claude Desktop과 같은 도구에서 대화형 에이전트 워크플로에 사용하세요.

• Python SDK는 스크립트, 자동화, 대시보드, 알림, 백테스트 및 애플리케이션 코드에 사용하세요.

SDK 저장소: sahmk-sa/sahmk-python

API 키 받기

1. sahmk.sa/developers에서 가입하세요.

2. 대시보드 → API 키 → 키 생성으로 이동하세요.

3. 키를 복사하세요(shmk_live_ 또는 shmk_test_로 시작).

시장 깊이 접근

get_depth는 권한 게이트가 적용됩니다. 개발자 대시보드에서 실시간/깊이 접근을 요청하세요:

실시간 접근 요청

필수 환경 변수

SAHMK_API_KEY는 모든 서버 실행(Claude Desktop, Cursor 및 직접 CLI 사용)에 필요합니다.
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

현재 MCP-SDK 호환성(기본 호스트 api.sahmk.sa, 시장 깊이, 실시간 체결 및 이벤트 도구)을 위해 sahmk>=0.16.0이 필요합니다.

보안

• API 키는 환경 변수(SAHMK_API_KEY)로 설정하세요.

• 키를 소스 제어에 커밋하거나 로그에 공유하지 마세요.

• 노출된 키는 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. 페이지네이션 루프의 경우 total에 도달할 때까지 offset을 limit만큼 증가:

   • 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 오류를 표시합니다. 참고: 장중(intraday) 과거 구간(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 필요); app.sahmk.sa는 SAHMK_BASE_URL을 통해 계속 지원.

• 0.6.0: sahmk>=0.14.0 필요; 최근 실시간 체결 내역(Pro+)을 위한 get_trades 추가.

• 0.5.1: README에 market-depth 권한 요청 링크를 문서화.

• 0.5.0: sahmk>=0.13.0 필요; get_depth(호가창 래더) 및 get_events(AI 이벤트 요약, Pro+) 추가.

• 0.4.7: 공개 get_financials 도구 계약에서 include_quality를 제거하고, 식별자 충돌 검사 전에 동등한 아랍-인도/ASCII 숫자 입력을 정규화하며, 안정적인 비율/기간 옵션을 위한 enum 선택기로 Glama 폼 UX를 개선.

• 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으로 확장; 장중(intraday) 플랜 제한 동작을 문서화.

• 0.4.4: 문서: 공식 배포 채널(GitHub + PyPI만)을 명확히 함.

• 0.4.3: MCP 출력 계약을 정렬: financials meta 없음; analytics meta는 period, metrics, warnings로 제한.

• 0.4.2: analytics에 SDK 메서드 이름 호환성 폴백(get_ratios/ratios, compare_symbols/compare)을 추가.

• 0.4.1: 패키지 종속성 및 런타임 버전 가드에서 sahmk>=0.9.1을 요구.

• 0.4.0: analytics 비율 및 비교 도구를 추가; financials 선택적 매개변수를 개선.

라이선스

MIT — LICENSE 참조