韓国投資証券 REST API MCP (Model Context Protocol)

韓国投資証券(KIS) REST APIをMCPツールとして呼び出すサーバーです。国内/海外株式照会、口座照会、注文関連APIを、カタログベースの汎用ツールおよび頻繁に使用する便利なツールとして提供します。

主な機能

• APIカタログベースの呼び出し

  • 8つのグループ、166個のREST APIを提供

  • APIグループ/ID、パス、HTTPメソッド、TR_ID候補、リクエストパラメータの確認

  • パラメータごとの韓国語ラベル、入力ガイド、例示値、主要コード値の提供

  • 全リスト: API_CATALOG.md

• 国内株式

  • 現在値、期間/日別相場、板情報、業種指数、基本情報の照会

  • 残高、投資口座資産状況、買付可能金額、売却可能数量の照会

  • 注文/注文履歴/訂正・取消可能注文の照会

• 海外株式

  • 米国、日本、中国、香港、ベトナム市場コードをサポート

  • 現在値、残高、約定基準現在残高、通貨別証拠金、買付可能金額の照会

  • 市場/売買方向に応じた注文TR_IDの自動選択

• 実行/運用

  • stdio, sse, streamable-http トランスポートをサポート

  • .env またはコマンドライン引数ベースの設定

  • 口座番号、口座商品コード、認証値の自動補完

  • アプリキーと口座タイプに基づくトークンキャッシュ

  • 不明なリクエストパラメータのデフォルト拒否

  • 注文/訂正/取消APIのデフォルトブロック

Related MCP server: kiwoom-mcp

安全のためのデフォルト設定

注文/訂正/取消のように口座状態を変更するAPIは、デフォルトでブロックされています。

KIS_ENABLE_TRADING=true

上記値を明示的に設定した場合にのみ、状態変更APIが実行されます。照会APIのみを使用する場合は設定しないでください。

要件

• Python >= 3.13

• uv

インストール

インストールは INSTALL.md に従って進めてください。LLMやMCPクライアントが設定する際も、このファイルを優先的に参照してください。

INSTALL.md には以下の内容が含まれています。

• uv ベースの依存関係インストール

• .env の作成と KIS_APP_KEY, KIS_APP_SECRET, KIS_CANO, KIS_ACNT_PRDT_CD の設定

• Codex CLI, Claude Code, Claude Desktop, 一般的なMCPクライアントの登録例

• コンテキスト節約用の KIS_MCP_TOOLSET=catalog 設定

• 残高、買付可能金額、現在値照会用の call-kis-api 例

ローカルでの迅速な準備:

pip install uv
uv sync
cp .env.example .env
chmod 600 .env

次に .env に以下の値を設定します。詳細な値の説明とクライアント別の登録コマンドは INSTALL.md を参照してください。

KIS_APP_KEY="발급받은 앱키"
KIS_APP_SECRET="발급받은 시크릿키"
KIS_ACCOUNT_TYPE="REAL"   # REAL 또는 VIRTUAL
KIS_CANO="계좌번호 앞 8자리"
KIS_ACNT_PRDT_CD="01"
KIS_MCP_TOOLSET="catalog"

実行

# stdio, 로컬 MCP 클라이언트 권장
uv run python server.py

コマンドライン引数でも設定可能です。

uv run python server.py \
  --app-key "앱키" \
  --app-secret "시크릿키" \
  --account-type "REAL" \
  --cano "계좌번호" \
  --acnt-prdt-cd "01"

トランスポートの選択:

MCP_TYPE=stdio uv run python server.py
MCP_TYPE=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/mcp uv run python server.py
MCP_TYPE=sse MCP_HOST=127.0.0.1 MCP_PORT=8000 MCP_PATH=/sse uv run python server.py

MCPクライアント登録例:

以下は一般的なMCPクライアント用の最小構成例です。Codex CLI, Claude Code, Claude Desktopのコマンドは INSTALL.md を使用してください。

{
  "mcpServers": {
    "kis-mcp-server": {
      "command": "uv",
      "args": ["run", "python", "server.py"],
      "cwd": "<project-root>",
      "env": {
        "KIS_MCP_TOOLSET": "catalog",
        "KIS_MCP_LOG_LEVEL": "WARNING"
      }
    }
  }
}

MCPツールの構成

カタログツール

list-kis-api-specs は必須パラメータのラベル、例示値、主要コード値を併せて返します。 get-kis-api-spec は全パラメータの label, guide, examples, values, default, auto_fill 情報を返すため、LLMが呼び出しに必要な入力形式を即座に確認できます。

call-kis-api は以下の処理を共通で行います。

• 環境変数ベースの口座番号/口座商品コードの自動入力

• 認証トークンの発行およびキャッシュ

• GET/POSTリクエストの構成

• 複数のTR_IDの中から自動判別可能な注文TR_IDを選択

• 状態変更APIの安全ゲート適用

• カタログにないパラメータのデフォルト拒否

便利なツール

頻繁に使用する国内/海外株式機能は、別途MCPツールとしても提供しています。

注文ツールも KIS_ENABLE_TRADING=true がなければ実行されません。

ツールのロード最適化

MCPクライアントはサーバー接続時にツール名、説明、入力スキーマをコンテキストに読み込みます。便利なツールを多く公開するほど対話開始時のコンテキスト使用量が増えるため、必要な場合はカタログツール3つのみを公開する軽量モードを使用できます。

KIS_MCP_TOOLSET=catalog uv run python server.py

catalog モードはMCPツールスキーマの読み込み量を減らすためのモードです。便利なツールは隠しますが、166個のAPIはそのまま call-kis-api で呼び出すことができます。必要なAPIは list-kis-api-specs で探し、必要な詳細パラメータは get-kis-api-spec でその都度照会すればよいです。

推奨される使用フロー:

1. list-kis-api-specs でAPIを検索します。

2. get-kis-api-spec で必須パラメータ、例示値、コード値を確認します。

3. call-kis-api で実際のAPIを呼び出します。

MCPクライアント設定でも環境変数を追加するだけです。

{
  "env": {
    "KIS_MCP_TOOLSET": "catalog"
  }
}

頻繁に使用する便利なツールをツールリストに直接表示したい場合は、デフォルト値の full を使用してください。

call-kis-api の例

国内株式現在値:

{
  "group": "domestic_stock",
  "api_type": "inquire_price",
  "params": {
    "fid_cond_mrkt_div_code": "J",
    "fid_input_iscd": "005930"
  }
}

海外株式残高:

{
  "group": "overseas_stock",
  "api_type": "inquire_balance",
  "params": {
    "ovrs_excg_cd": "NASD",
    "tr_crcy_cd": "USD"
  }
}

海外株式約定基準現在残高:

{
  "group": "overseas_stock",
  "api_type": "inquire_present_balance",
  "params": {
    "wcrc_frcr_dvsn_cd": "01",
    "natn_cd": "000",
    "tr_mket_cd": "00",
    "inqr_dvsn_cd": "00"
  }
}

海外株式買付可能金額:

{
  "group": "overseas_stock",
  "api_type": "inquire_psamount",
  "params": {
    "ovrs_excg_cd": "NASD",
    "ovrs_ord_unpr": "1",
    "item_cd": "QQQ"
  }
}

主なAPIグループ

全API ID、パス、TR_ID、必須パラメータガイドは API_CATALOG.md にまとめられています。

環境変数

開発/検証

uv run python -m compileall main.py server.py example.py tests
uv run python -m unittest discover -v
git diff --check

ライセンス

MIT