MCP (Protocolo de Contexto de Modelos) para la API REST de Korea Investment & Securities

Este es un servidor que invoca la API REST de Korea Investment & Securities (KIS) como herramientas MCP. Proporciona APIs para consultas de acciones nacionales/extranjeras, consultas de cuentas y pedidos, tanto a través de herramientas generales basadas en catálogo como de herramientas de conveniencia de uso frecuente.

Funciones principales

• Invocación basada en catálogo de API

  • Proporciona 166 APIs REST en 8 grupos

  • Verificación de grupo/ID de API, ruta, método HTTP, candidatos a TR_ID y parámetros de solicitud

  • Proporciona etiquetas en coreano, guías de entrada, valores de ejemplo y códigos principales para cada parámetro

  • Lista completa: API_CATALOG.md

• Acciones nacionales

  • Consulta de precio actual, cotizaciones por período/día, libro de órdenes, í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 pedidos, historial de pedidos y pedidos corregibles/cancelables

• Acciones extranjeras

  • Soporte para códigos de mercado de EE. UU., Japón, China, Hong Kong y Vietnam

  • Consulta de precio actual, saldo, saldo actual basado en ejecución, margen por moneda y monto disponible para compra

  • Selección automática de TR_ID de pedido según el mercado y la dirección de compra/venta

• Ejecución/Operación

  • Soporte para transporte stdio, sse, streamable-http

  • Configuración basada en .env o argumentos de línea de comandos

  • Autocompletado 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 predeterminado de parámetros de solicitud desconocidos

  • Bloqueo predeterminado de APIs de pedido/corrección/cancelación

Related MCP server: kiwoom-mcp

Valores predeterminados de seguridad

Las APIs que modifican el estado de la cuenta, como pedidos/correcciones/cancelaciones, están bloqueadas de forma predeterminada.

KIS_ENABLE_TRADING=true

Las APIs de cambio de estado solo se ejecutan si se configuran explícitamente los valores anteriores. Si solo utiliza APIs de consulta, no los configure.

Requisitos

• Python >= 3.13

• uv

Instalación

Siga las instrucciones en INSTALL.md para la instalación. Los LLM o clientes MCP también deben leer este archivo primero al realizar la configuración.

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 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

Luego, configure los siguientes valores en .env. Consulte INSTALL.md para obtener explicaciones detalladas de los valores y 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 de cliente MCP:

A continuación se muestra un ejemplo mínimo para un cliente MCP general. 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

list-kis-api-specs devuelve etiquetas, valores de ejemplo y códigos principales de los parámetros obligatorios. get-kis-api-spec devuelve información de label, guide, examples, values, default y auto_fill de todos los parámetros, permitiendo al LLM verificar inmediatamente el formato de entrada necesario para la llamada.

call-kis-api realiza los siguientes procesos de forma común:

• 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

• Configuración de solicitudes GET/POST

• Selección automática de TR_ID de pedido entre múltiples candidatos

• Aplicación de puerta de seguridad para APIs de cambio de estado

• Rechazo predeterminado de parámetros no presentes en el catálogo

Herramientas de conveniencia

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

Las herramientas de pedido tampoco se ejecutarán sin KIS_ENABLE_TRADING=true.

Optimización de carga de herramientas

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

KIS_MCP_TOOLSET=catalog uv run python server.py

El modo catalog es para reducir la carga del esquema de herramientas MCP. Aunque oculta las herramientas de conveniencia, las 166 APIs se pueden seguir invocando a través de call-kis-api. Puede buscar la API necesaria con list-kis-api-specs y consultar los parámetros detallados necesarios con get-kis-api-spec en el momento.

Flujo de uso recomendado:

1. Busque la API con list-kis-api-specs.

2. Verifique los parámetros obligatorios, valores de ejemplo y códigos con get-kis-api-spec.

3. Invoque la API real con call-kis-api.

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

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

Si desea exponer las herramientas de conveniencia de uso frecuente directamente en la lista de herramientas, utilice 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 de acciones extranjeras basado en ejecución:

{
  "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 de API principales

El ID completo de la API, la ruta, el TR_ID y la guía de parámetros obligatorios se resumen en API_CATALOG.md.

Variables de entorno

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

Licencia

MIT