한국투자증권 REST API MCP (Model Context Protocol)

한국투자증권 REST API MCP（Model Context Protocol）

这是一个将韩国投资证券（KIS）REST API 作为 MCP 工具调用的服务。它提供基于目录的通用工具和常用便捷工具，用于查询韩国国内／海外股票、账户及订单相关 API。

注意

本项目是由个人／社区运营的非官方开源项目，与韩国投资证券、KIS Developers、true friend 韩国投资 Open API 不存在合作、赞助、批准或官方发布关系。 用户需自行承担因使用本项目而产生的所有责任，包括安装、设置、API 调用、账户查询、执行订单、投资决策及由此造成的损失、故障或安全问题。 实际交易前，请亲自核实韩国投资证券官方文档和输入值。

主要功能

• 基于 API 目录调用
  • 提供 8 个分组、166 个 REST API
  • 查看 API 分组／ID、路径、HTTP 方法、TR_ID 候选项及请求参数
  • 提供各参数的韩文标签、输入指南、示例值和主要代码值
  • 完整列表：API_CATALOG.md
• 韩国国内股票
  • 查询当前价格、周期／每日行情、报价、行业指数和基本信息
  • 查询余额、投资账户资产状况、可买金额和可卖数量
  • 查询订单、订单记录及可修改／取消的订单
• 海外股票
  • 支持美国、日本、中国、香港、越南市场代码
  • 查询当前价格、余额、按成交计算的当前余额、各币种保证金和可买金额
  • 根据市场及买卖方向自动选择订单 TR_ID
• 运行／运维
  • 支持 stdio、sse、streamable-http transport
  • 基于 .env 或命令行参数进行设置
  • 自动补全账户号码、账户产品代码和认证值
  • 根据应用密钥和账户类型缓存令牌
  • 默认拒绝未知请求参数
  • 默认阻止订单／修改／取消 API

安全默认设置

默认会阻止会更改账户状态的 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"

选择 Transport：

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	按 API 分组／搜索词查询列表
get-kis-api-spec	查看单个 API 的路径、TR_ID 候选项及参数
call-kis-api	使用 group、api_type、params 调用目录中的 API

list-kis-api-specs 会同时返回必填参数的标签、示例值和主要代码值。 get-kis-api-spec 会返回所有参数的 label、guide、examples、values、default、auto_fill 信息，因此 LLM 可以直接查看调用所需的输入格式。

call-kis-api 会统一执行以下处理：

• 根据环境变量自动填入账户号码／账户产品代码
• 获取并缓存认证令牌
• 构建 GET/POST 请求
• 部分 MCP 客户端会将 params 作为 JSON 字符串发送，此时将其解析为对象
• 从多个 TR_ID 中选择可自动判别的订单 TR_ID
• 应用状态变更 API 安全门控
• 默认拒绝目录中未列出的参数

便捷工具

常用的韩国国内／海外股票功能也提供独立的 MCP 工具。

工具	说明
inquery-stock-price	查询韩国国内股票当前价格
inquery-balance	查询韩国国内股票余额
inquery-order-list	查询韩国国内股票每日订单／成交记录
inquery-order-detail	查询韩国国内股票订单详情
inquery-stock-info	查询韩国国内股票每日行情
inquery-stock-history	查询韩国国内股票周期行情
inquery-stock-ask	查询韩国国内股票报价
inquery-stock-market	查询韩国国内行业／指数当前价格
inquery-stock-basic-info	查询韩国国内股票基本信息
inquery-overseas-stock-price	查询海外股票当前价格
order-stock	韩国国内股票买入／卖出订单
order-overseas-stock	海外股票买入／卖出订单

如果未设置 KIS_ENABLE_TRADING=true，订单工具也不会执行。

도구 로드 최적화

MCP 클라이언트는 서버 연결 시 도구 이름, 설명, 입력 스키마를 컨텍스트에 올립니다. 편의 도구를 많이 노출할수록 대화 시작 시점의 컨텍스트 사용량이 늘어나므로, 필요한 경우 카탈로그 도구 3개만 노출하는 경량 모드를 사용할 수 있습니다.

KIS_MCP_TOOLSET=catalog uv run python server.py

값	노출 도구 수	노출 도구	용도
full	15개	카탈로그 도구 + 편의 도구 전체	기존 동작과 호환
catalog	3개	list-kis-api-specs, get-kis-api-spec, call-kis-api	낮은 컨텍스트 사용량

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 수
auth	인증	2
domestic_stock	국내주식	74
overseas_stock	해외주식	34
domestic_bond	국내채권	14
domestic_futureoption	국내선물옵션	20
overseas_futureoption	해외선물옵션	19
elw	ELW	1
etfetn	ETF/ETN	2

전체 API ID, 경로, TR_ID, 필수 파라미터 가이드는 API_CATALOG.md에 정리되어 있습니다.

환경 변수

이름	설명	기본값
KIS_APP_KEY	KIS 앱키	-
KIS_APP_SECRET	KIS 시크릿키	-
KIS_ACCOUNT_TYPE	REAL 또는 VIRTUAL	-
KIS_CANO	계좌번호 앞 8자리	-
KIS_ACNT_PRDT_CD	계좌상품코드	01
KIS_TOKEN_FILE	토큰 캐시 파일	token.json
KIS_ENABLE_TRADING	주문/정정/취소 API 활성화	비활성
KIS_MCP_TOOLSET	MCP 도구 노출 범위 (full, catalog)	full
KIS_MCP_LOG_LEVEL	로그 레벨	INFO
MCP_TYPE	stdio, sse, streamable-http	stdio
MCP_HOST	HTTP/SSE host	127.0.0.1
MCP_PORT	HTTP/SSE port	8000
MCP_PATH	HTTP/SSE path	/mcp

개발/검증

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

Contributors

AI 공동작성자는 기여자 목록에서 제외했습니다.

Contributor	Role
migusdn	Maintainer
mickeykim70	Contributor
haesam5060-arch	Contributor

라이선스

MIT