Korea Investment & Securities (KIS) REST API

Proporciona operaciones bursátiles y datos de mercado utilizando la API REST de Korea Investment & Securities (KIS).

Documentación

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

Este es un servidor que invoca la API REST de Korea Investment & Securities (KIS) como herramientas MCP. Proporciona consultas de acciones nacionales/extranjeras, consultas de cuentas y API relacionadas con órdenes mediante herramientas universales basadas en catálogo y herramientas de conveniencia de uso frecuente.

Advertencia

Este proyecto es un proyecto de código abierto no oficial operado por individuos/comunidad y no tiene relación de afiliación, patrocinio, aprobación ni distribución oficial con Korea Investment & Securities, KIS Developers o true friend 한국투자 Open API. Toda la responsabilidad por la instalación, configuración, llamadas a la API, consulta de cuentas, ejecución de órdenes, decisiones de inversión y las pérdidas, fallos o problemas de seguridad resultantes del uso de este proyecto recae en el usuario. Antes de realizar transacciones reales, verifique directamente los documentos oficiales de Korea Investment & Securities y los valores de entrada.

Características principales

Llamadas basadas en catálogo de API
- Proporciona 166 API REST en 8 grupos
- Consulta de grupo/ID de API, ruta, método HTTP, candidatos TR_ID y parámetros de solicitud
- Proporciona etiquetas en coreano por parámetro, guía de entrada, valores de ejemplo y valores de código principales
- Lista completa: API_CATALOG.md
Acciones nacionales
- Consulta de precio actual, cotizaciones por período/día, cotizaciones de oferta/demanda, índices sectoriales e información básica
- Consulta de saldo, estado de activos de la cuenta de inversión, monto disponible para compra y cantidad disponible para venta
- Consulta de órdenes, historial de órdenes y órdenes modificables o cancelables
Acciones extranjeras
- Soporte de códigos de mercado de EE. UU., Japón, China, Hong Kong y Vietnam
- Consulta de precio actual, saldo, saldo actual según ejecución, margen por moneda y monto disponible para compra
- Selección automática de TR_ID de orden según mercado y dirección de compra/venta
Ejecución/Operación
- Soporte de transporte stdio, sse, streamable-http
- Configuración basada en .env o argumentos de línea de comandos
- Completado automático de número de cuenta, código de producto de cuenta y valores de autenticación
- Caché de tokens basada en clave de aplicación y tipo de cuenta
- Rechazo por defecto de parámetros de solicitud desconocidos
- Bloqueo por defecto de API de órdenes/modificación/cancelación

Valores seguros por defecto

Las API que cambian el estado de la cuenta, como órdenes/modificación/cancelación, están bloqueadas por defecto.

KIS_ENABLE_TRADING=true

Las API de cambio de estado solo se ejecutan si configura explícitamente el valor anterior. No lo configure si solo utiliza API de consulta.

Requisitos

Python >= 3.13
uv

Instalación

Realice la instalación según INSTALL.md. Los LLM o clientes MCP también deben leer este archivo primero al configurar.

INSTALL.md incluye el siguiente contenido.

Instalación de dependencias basada en uv
Creación de .env y configuración de KIS_APP_KEY, KIS_APP_SECRET, KIS_CANO, KIS_ACNT_PRDT_CD
Ejemplos de registro para Codex CLI, Claude Code, Claude Desktop y clientes MCP generales
Configuración de KIS_MCP_TOOLSET=catalog para ahorrar contexto
Ejemplo de call-kis-api para consultar saldo, monto disponible para compra y precio actual

Preparación local rápida:

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

A continuación, configure los siguientes valores en .env. Consulte INSTALL.md para obtener una explicación detallada de los valores y los comandos de registro por cliente.

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

Ejecución

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

También se puede configurar mediante argumentos de línea de comandos.

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

Selección de transporte:

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

Ejemplo de registro en cliente MCP:

A continuación se muestra un ejemplo mínimo para clientes MCP generales. Utilice INSTALL.md para los comandos de Codex CLI, Claude Code y Claude Desktop.

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

Configuración de herramientas MCP

Herramientas de catálogo

Herramienta	Descripción
`list-kis-api-specs`	Consulta de lista por grupo de API/término de búsqueda
`get-kis-api-spec`	Consulta de ruta, candidatos TR_ID y parámetros de una API individual
`call-kis-api`	Llamada a API de catálogo con `group`, `api_type`, `params`

list-kis-api-specs devuelve también las etiquetas, valores de ejemplo y valores de código principales de los parámetros obligatorios. get-kis-api-spec devuelve la información label, guide, examples, values, default, auto_fill de todos los parámetros, por lo que el LLM puede ver inmediatamente el formato de entrada necesario para la llamada.

call-kis-api realiza de forma común el siguiente procesamiento.

Entrada automática de número de cuenta/código de producto de cuenta basada en variables de entorno
Emisión y caché de tokens de autenticación
Construcción de solicitudes GET/POST
Análisis como objeto cuando algunos clientes MCP envían params como cadena JSON
Selección del TR_ID de orden identificable automáticamente entre múltiples TR_ID
Aplicación de puerta de seguridad para API de cambio de estado
Rechazo por defecto de parámetros que no están en el catálogo

Herramientas de conveniencia

Las funciones de acciones nacionales/extranjeras de uso frecuente también se proporcionan como herramientas MCP independientes.

Herramienta	Descripción
`inquery-stock-price`	Consulta de precio actual de acciones nacionales
`inquery-balance`	Consulta de saldo de acciones nacionales
`inquery-order-list`	Consulta de órdenes/ejecuciones diarias de acciones nacionales
`inquery-order-detail`	Consulta de detalle de orden de acciones nacionales
`inquery-stock-info`	Consulta de cotizaciones diarias de acciones nacionales
`inquery-stock-history`	Consulta de cotizaciones por período de acciones nacionales
`inquery-stock-ask`	Consulta de cotizaciones de oferta/demanda de acciones nacionales
`inquery-stock-market`	Consulta de precio actual de sectores/índices nacionales
`inquery-stock-basic-info`	Consulta de información básica de acciones nacionales
`inquery-overseas-stock-price`	Consulta de precio actual de acciones extranjeras
`order-stock`	Orden de compra/venta de acciones nacionales
`order-overseas-stock`	Orden de compra/venta de acciones extranjeras

Las herramientas de órdenes tampoco se ejecutan sin KIS_ENABLE_TRADING=true.

Optimización de carga de herramientas

El cliente MCP carga los nombres, descripciones y esquemas de entrada de las herramientas en el contexto al conectarse al servidor. Cuantas más herramientas de conveniencia se expongan, mayor será el uso de contexto al inicio de la conversación, por lo que puede usar un modo ligero que exponga solo las 3 herramientas de catálogo si es necesario.

KIS_MCP_TOOLSET=catalog uv run python server.py

Valor	N.º de herramientas expuestas	Herramientas expuestas	Uso
`full`	15	Herramientas de catálogo + todas las herramientas de conveniencia	Compatible con el comportamiento existente
`catalog`	3	`list-kis-api-specs`, `get-kis-api-spec`, `call-kis-api`	Bajo uso de contexto

El modo catalog es un modo para reducir la cantidad de esquemas de herramientas MCP cargados. Oculta las herramientas de conveniencia, pero las 166 API se pueden seguir llamando con call-kis-api. Busque la API necesaria con list-kis-api-specs y consulte los parámetros detallados necesarios con get-kis-api-spec cuando los necesite.

Flujo de uso recomendado:

Busque la API con list-kis-api-specs.
Verifique los parámetros obligatorios, valores de ejemplo y valores de código con get-kis-api-spec.
Llame a la API real con call-kis-api.

En la configuración del cliente MCP, solo necesita agregar la variable de entorno.

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

Si desea exponer directamente las herramientas de conveniencia de uso frecuente en la lista de herramientas, use el valor predeterminado full.

Ejemplo de `call-kis-api`

Precio actual de acciones nacionales:

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

Saldo de acciones extranjeras:

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

Saldo actual según ejecución de acciones extranjeras:

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

Monto disponible para compra de acciones extranjeras:

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

Grupos principales de API

Grupo	Descripción	N.º de API
`auth`	Autenticación	2
`domestic_stock`	Acciones nacionales	74
`overseas_stock`	Acciones extranjeras	34
`domestic_bond`	Bonos nacionales	14
`domestic_futureoption`	Futuros/opciones nacionales	20
`overseas_futureoption`	Futuros/opciones extranjeros	19
`elw`	ELW	1
`etfetn`	ETF/ETN	2

La guía completa de ID de API, rutas, TR_ID y parámetros obligatorios está organizada en API_CATALOG.md.

Variables de entorno

Nombre	Descripción	Valor predeterminado
`KIS_APP_KEY`	Clave de aplicación KIS	-
`KIS_APP_SECRET`	Clave secreta KIS	-
`KIS_ACCOUNT_TYPE`	`REAL` o `VIRTUAL`	-
`KIS_CANO`	Primeros 8 dígitos del número de cuenta	-
`KIS_ACNT_PRDT_CD`	Código de producto de cuenta	`01`
`KIS_TOKEN_FILE`	Archivo de caché de tokens	`token.json`
`KIS_ENABLE_TRADING`	Habilitar API de órdenes/modificación/cancelación	Deshabilitado
`KIS_MCP_TOOLSET`	Alcance de exposición de herramientas MCP (`full`, `catalog`)	`full`
`KIS_MCP_LOG_LEVEL`	Nivel de registro	`INFO`
`MCP_TYPE`	`stdio`, `sse`, `streamable-http`	`stdio`
`MCP_HOST`	Host HTTP/SSE	`127.0.0.1`
`MCP_PORT`	Puerto HTTP/SSE	`8000`
`MCP_PATH`	Ruta HTTP/SSE	`/mcp`

Desarrollo/Verificación

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

Contributors

Los coautores de IA se excluyeron de la lista de contribuyentes.

Contributor	Role
migusdn	Maintainer
mickeykim70	Contributor
haesam5060-arch	Contributor

Licencia

MIT

Korea Investment & Securities (KIS) REST API

Documentación