Ko Stock

ko-stock-mcp

韓国の DART（전자공시시스템、金融監督院電子開示システム） データを、Claude Desktop などの MCP クライアントに提供する MCP サーバーです。

한국어 문서는 README.ko.md를 참고하세요.

ツール

DART（電子開示）と KRX（韓国取引所）の両方のツールを提供します。

DART（開示）

ツール	説明
get_corp_code	会社名または証券コード（6 桁）で、会社の DART corp_code（8 桁）を検索します。他のツールを使う際の起点です。
get_company_info	会社概要（会社名、CEO、市場区分、業種、設立日など）。
get_disclosure_list	会社、期間、開示種別で開示情報を検索します。
get_disclosure	開示の原文書を取得します。大きな文書では目次（toc）が返されます。section_id を指定して詳細を取得します。
get_financial_statement	定期報告書の XBRL 財務諸表（BS / IS / CIS / SCE / CF）。
get_today_date	KST/UTC での今日の日付（YYYYMMDD + ISO）。

KRX（韓国取引所）— KRX_API_KEY が必要です

ツール	説明
get_market_type	証券コードがどの市場（KOSPI/KOSDAQ/KONEX）に属するかを判定します。まず DART の会社区分を使用し、該当しない場合は KRX にフォールバックします。
get_stock_trade_info	営業日の取引データ（日次終値、変動率、出来高、時価総額など）。
get_stock_base_info	株式の基本情報（名称、標準コード／短縮コード、上場日、額面、発行済株式数など）。

一般的な流れ — 開示／財務情報：get_corp_code →（get_disclosure_list | get_financial_statement | get_company_info）→ 全文を取得するには get_disclosure。市場データ： （必要に応じて get_market_type →）get_stock_trade_info | get_stock_base_info（bas_dd には営業日を指定する必要があります。取引のない日は空の結果が返されます）。

KRX_API_KEY が設定されていない場合、KRX ツールは分かりやすいエラーを返します。DART の機能には影響しません。 get_market_type は DART のキーだけでも（会社区分を使って）動作します。

KRX のレスポンスフィールド

get_stock_trade_info / get_stock_base_info は、KRX の生フィールドをそのまま result の下に返します（金額／数量は文字列、日付は YYYYMMDD です）。

get_stock_trade_info（日次取引データ）

フィールド	意味
BAS_DD	基準日（YYYYMMDD）
ISU_CD	証券コード（このレスポンスでは 6 桁の短縮コード）
ISU_NM	銘柄名
MKT_NM	市場（KOSPI/KOSDAQ/KONEX）
SECT_TP_NM	部門／市場区分
TDD_CLSPRC	終値
CMPPREVDD_PRC	前日比
FLUC_RT	変動率（%）
TDD_OPNPRC / TDD_HGPRC / TDD_LWPRC	始値／高値／安値
ACC_TRDVOL	累計取引量（株）
ACC_TRDVAL	累計取引額（KRW）
MKTCAP	時価総額（KRW）
LIST_SHRS	上場株式数

get_stock_base_info（株式の基本情報）

フィールド	意味
ISU_CD	標準コード（12 桁、例：KR7005930003）
ISU_SRT_CD	短縮コード（6 桁、例：005930）
ISU_NM	正式な銘柄名
ISU_ABBRV	略称
ISU_ENG_NM	英語名
LIST_DD	上場日（YYYYMMDD）
MKT_TP_NM	市場（KOSPI/KOSDAQ/KONEX）
SECUGRP_NM	証券グループ（例：普通株）
SECT_TP_NM	部門／市場区分
KIND_STKCERT_TP_NM	株式の種類（例：普通株）
PARVAL	額面
LIST_SHRS	上場株式数

get_market_type は { "market": "KOSPI"|"KOSDAQ"|"KONEX", "source": "dart"|"krx"|"cache" } を返します（source は分類の取得元です）。

必要条件

• Python >= 3.10
• uv
• DART Open API キー — https://opendart.fss.or.kr で登録します（無料、即時発行）。
• （任意）KRX Open API キー — https://openapi.krx.co.kr で登録してキーを申請し、6 つの株式サービス（日次取引 3 件 + 基本情報 3 件）を申し込みます。承認には約 1 日かかります。 KRX の市場データツールにのみ必要です。

セットアップ

uv sync
cp .env.example .env   # then put your DART_API_KEY in .env

実行／開発

# Launch the MCP Inspector for local testing
uv run mcp dev src/ko_stock_mcp/server.py

# Or run the server directly (stdio)
uv run ko-stock-mcp

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "ko-stock-mcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ko-stock-mcp", "run", "python", "-m", "ko_stock_mcp.server"]
    }
  }
}

uv --directory はこのプロジェクトを作業ディレクトリとしてサーバーを実行するため、.env （DART_API_KEY と、任意で KRX_API_KEY を含む）は自動的に読み込まれます。そのため、ここでキーを 重複して指定する必要はありません。必要に応じて、代わりに明示的に渡すこともできます：

"env": { "DART_API_KEY": "<YOUR_DART_API_KEY>", "KRX_API_KEY": "<YOUR_KRX_API_KEY>" }

macOS では、設定ファイルは ~/Library/Application Support/Claude/claude_desktop_config.json にあります。編集後、Claude Desktop を再起動してください。

ライセンス

MIT — LICENSE を参照してください。