Korean Stock Search

このスキルが行うこと

基本的に https://k-skill-proxy.nomadamas.org/v1/korean-stock/... にリクエストを送って、KRX 上場銘柄の検索、銘柄の基本情報、日別の株価を照会します。

アップストリーム設計の参考は jjlabsio/korea-stock-mcp ですが、ユーザーは KRX_API_KEY を取得したり、ローカル MCP サーバーをインストールする必要がありません。KRX_API_KEY はプロキシサーバーでのみ管理されます。

使用する場合

• 「サムスン電子の銘柄コードと市場区分を探して」
• 「005930 の基本情報を見せて」
• 「SK ハイニックス 20260408 の終値/出来高を教えて」
• 「KOSDAQ で Altogen の株価を確認して」

使用しない場合

• 米国/日本/仮想資産などの非韓国株式の照会
• リアルタイム約定/気配値/分足の照会
• 財務諸表/公示原文の分析（このスキルの範囲外）
• 投資アドバイス/買い推奨

入力値

• q: 銘柄名または銘柄コード検索語（search エンドポイント）
• market: KOSPI | KOSDAQ | KONEX
• code: 銘柄コード（通常 6 桁の短縮コード、例: 005930）
• bas_dd: 基準日 YYYYMMDD（ない場合は KST 本日の日付がデフォルト、休場日の場合は最近の営業日で再試行）
• limit: 検索結果数（デフォルト 10、最大 20）

前提条件

なし。ユーザーは KRX_API_KEY を準備する必要がありません。アップストリームキーはプロキシサーバーでのみ注入されます。

デフォルトパス

追加のクライアント API レイヤーは不要です。プロキシサーバーに HTTP リクエストを送るだけです。

KSKILL_PROXY_BASE_URL 環境変数がある場合はその値を使用し、ない場合はデフォルトパス https://k-skill-proxy.nomadamas.org を使用します。

サポートされるエンドポイント

銘柄検索

GET /v1/korean-stock/search?q={検索語}&bas_dd={YYYYMMDD}

銘柄基本情報

GET /v1/korean-stock/base-info?market={KOSPI|KOSDAQ|KONEX}&code={銘柄コード}&bas_dd={YYYYMMDD}

銘柄日別株価

GET /v1/korean-stock/trade-info?market={KOSPI|KOSDAQ|KONEX}&code={銘柄コード}&bas_dd={YYYYMMDD}

リクエスト例

銘柄検索:

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/search' \
  --data-urlencode 'q=삼성전자' \
  --data-urlencode 'bas_dd=20260408'

銘柄基本情報:

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/base-info' \
  --data-urlencode 'market=KOSPI' \
  --data-urlencode 'code=005930' \
  --data-urlencode 'bas_dd=20260408'

銘柄日別株価:

curl -fsS --get 'https://k-skill-proxy.nomadamas.org/v1/korean-stock/trade-info' \
  --data-urlencode 'market=KOSPI' \
  --data-urlencode 'code=005930' \
  --data-urlencode 'bas_dd=20260408'

レスポンス形式

検索レスポンス

{
  "items": [
    {
      "market": "KOSPI",
      "code": "005930",
      "standard_code": "KR7005930003",
      "name": "삼성전자",
      "short_name": "삼성전자",
      "english_name": "Samsung Electronics",
      "listed_at": "1975-06-11"
    }
  ],
  "query": { "q": "삼성전자", "bas_dd": "20260408", "limit": 10 },
  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
}

基本情報レスポンス

{
  "item": {
    "market": "KOSPI",
    "code": "005930",
    "standard_code": "KR7005930003",
    "name": "삼성전자",
    "short_name": "삼성전자",
    "english_name": "Samsung Electronics",
    "security_group": "주권",
    "section_type": "대형주",
    "stock_certificate_type": "보통주",
    "par_value": 100,
    "listed_shares": 5969782550
  },
  "query": { "market": "KOSPI", "code": "005930", "bas_dd": "20260408" },
  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
}

日別株価レスポンス

{
  "item": {
    "market": "KOSPI",
    "code": "005930",
    "standard_code": "KR7005930003",
    "base_date": "20260408",
    "name": "삼성전자",
    "close_price": 84000,
    "change_price": 1000,
    "fluctuation_rate": 1.2,
    "open_price": 83000,
    "high_price": 84500,
    "low_price": 82800,
    "trading_volume": 12345678,
    "trading_value": 1030000000000,
    "market_cap": 500000000000000
  },
  "query": { "market": "KOSPI", "code": "005930", "bas_dd": "20260408" },
  "proxy": { "name": "k-skill-proxy", "cache": { "hit": false, "ttl_ms": 300000 } }
}

レスポンスポリシー

• 銘柄名が曖昧な場合は、まず search で市場/銘柄コードを絞った後、base-info または trade-info に進みます。
• 一部の市場アップストリームが失敗した場合は、upstream.degraded=true と failed_markets を報告して部分障害を説明します。
• trade-info の結果は日別スナップショットです。リアルタイムの気配値/約定のように述べません。
• 休場日/場中でデータがない場合は、最近の営業日で再試行します。この場合 trade-info は 502 ではなく not_found で終了する可能性があります。
• 数値は読みやすい単位（ウォン、株、億/兆）で簡潔に記載しながら、元の数値も保持します。
• 回答の最後に「KRX 公式データに基づく / 投資助言ではない」と簡潔に記載します。

回答は簡潔に

• 銘柄名 / 市場 / 銘柄コード
• 基準日
• 終値 / 変動率 / 出来高 / 時価総額
• 必要に応じてのみ上場日 / 上場株式数 / 額面価格
• 複数の候補がある場合は上位 3～5 個を表示し、ユーザーに選ばせます

エラーモード

• q、market、code、bas_dd の形式が正しくない場合は 400 レスポンス
• プロキシサーバーに KRX_API_KEY がない場合は 503 レスポンス
• 検索中に一部の市場アップストリームが失敗した場合は 200 レスポンスですが、upstream.degraded=true と failed_markets を返す可能性があります。
• すべてのリクエスト市場でアップストリーム KRX 照会が失敗した場合は 502 レスポンス
• 該当する基準日/市場に銘柄がない場合は 404 not_found

完了の条件

• 検索語が曖昧な場合は、search で候補を先に絞りました。
• 必要に応じて base-info と trade-info を呼び出して主要数値をまとめました。
• ユーザーが KRX_API_KEY なしで照会できることを維持しました。
• KRX 公式データに基づくことを簡潔に記載しました。

注記

• 原本参考: https://github.com/jjlabsio/korea-stock-mcp
• 公式データ出典: KRX Open API (https://openapi.krx.co.kr/contents/OPP/MAIN/main/index.cmd)
• このスキルはリードオンリー照会専用です。