Korea Investment & Securities (KIS) REST API MCP (Model Context Protocol)

This is a server that calls the Korea Investment & Securities (KIS) REST API as MCP tools. It provides domestic/foreign stock inquiries, account inquiries, and order-related APIs through both catalog-based general tools and frequently used convenience tools.

Key Features

• API Catalog-based Calls

  • Provides 166 REST APIs across 8 groups

  • Check API groups/IDs, paths, HTTP methods, TR_ID candidates, and request parameters

  • Provides Korean labels, input guides, example values, and major code values for each parameter

  • Full list: API_CATALOG.md

• Domestic Stocks

  • Inquire current price, period/daily quotes, quotes (order book), industry indices, and basic information

  • Inquire balance, investment account asset status, buyable amount, and sellable quantity

  • Inquire orders/order history/correctable/cancellable orders

• Foreign Stocks

  • Supports market codes for US, Japan, China, Hong Kong, and Vietnam

  • Inquire current price, balance, current balance based on execution, margin by currency, and buyable amount

  • Automatic selection of order TR_ID based on market/buy-sell direction

• Execution/Operation

  • Supports stdio, sse, and streamable-http transports

  • Configuration based on .env or command-line arguments

  • Automatic completion of account number, account product code, and authentication values

  • Token cache based on app key and account type

  • Default rejection of unknown request parameters

  • Default blocking of order/correction/cancellation APIs

Related MCP server: kiwoom-mcp

Safety Defaults

APIs that change account status, such as orders/corrections/cancellations, are blocked by default.

KIS_ENABLE_TRADING=true

Status change APIs are executed only when the above value is explicitly set. Do not set this if you are only using inquiry APIs.

Requirements

• Python >= 3.13

• uv

Installation

Proceed with installation based on INSTALL.md. LLMs or MCP clients should also read this file first when configuring.

INSTALL.md includes the following content:

• uv-based dependency installation

• .env creation and setting KIS_APP_KEY, KIS_APP_SECRET, KIS_CANO, KIS_ACNT_PRDT_CD

• Examples for registering with Codex CLI, Claude Code, Claude Desktop, and general MCP clients

• KIS_MCP_TOOLSET=catalog setting for context saving

• call-kis-api examples for balance, buyable amount, and current price inquiries

Quick local setup:

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

Then, set the following values in .env. Refer to INSTALL.md for detailed value descriptions and registration commands for each client.

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

Execution

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

You can also configure it via command-line arguments.

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

Transport selection:

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 client registration example:

Below is a minimal example for a general MCP client. Use INSTALL.md for Codex CLI, Claude Code, and Claude Desktop commands.

{
  "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 Tool Configuration

Catalog Tools

list-kis-api-specs returns labels, example values, and major code values for required parameters together. get-kis-api-spec returns label, guide, examples, values, default, and auto_fill information for all parameters, allowing the LLM to immediately verify the input format required for the call.

call-kis-api performs the following common processing:

• Automatic input of account number/account product code based on environment variables

• Authentication token issuance and caching

• GET/POST request configuration

• Automatic selection of order TR_ID among multiple TR_IDs

• Application of safety gate for status change APIs

• Default rejection of parameters not in the catalog

Convenience Tools

Frequently used domestic/foreign stock functions are also provided as separate MCP tools.

Order tools will not execute without KIS_ENABLE_TRADING=true.

Tool Loading Optimization

MCP clients load tool names, descriptions, and input schemas into the context when connecting to the server. Since exposing more convenience tools increases context usage at the start of a conversation, you can use a lightweight mode that exposes only the 3 catalog tools if necessary.

KIS_MCP_TOOLSET=catalog uv run python server.py

catalog mode is for reducing the MCP tool schema load. While convenience tools are hidden, all 166 APIs can still be called via call-kis-api. You can find the necessary API with list-kis-api-specs and look up required detailed parameters with get-kis-api-spec as needed.

Recommended usage flow:

1. Search for an API with list-kis-api-specs.

2. Check required parameters, example values, and code values with get-kis-api-spec.

3. Call the actual API with call-kis-api.

You only need to add environment variables in the MCP client settings as well.

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

If you want to expose frequently used convenience tools directly in the tool list, use the default value full.

call-kis-api Examples

Domestic stock current price:

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

Foreign stock balance:

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

Foreign stock current balance based on execution:

{
  "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"
  }
}

Foreign stock buyable amount:

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

Major API Groups

Full API IDs, paths, TR_IDs, and required parameter guides are summarized in API_CATALOG.md.

Environment Variables

Development/Verification

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

License

MIT