Korea Investment & Securities (KIS) REST API

Fornece negociação de ações e dados de mercado usando a Korea Investment & Securities (KIS) REST API.

Documentação

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

Este é um servidor que chama a API REST da Korea Investment & Securities (KIS) como ferramentas MCP. Ele fornece APIs de consulta de ações domésticas/estrangeiras, consulta de contas e ordens, como ferramentas universais baseadas em catálogo e ferramentas de conveniência de uso frequente.

Atenção

Este projeto é um projeto de código aberto não oficial operado por indivíduos/comunidade e não tem relação de parceria, patrocínio, aprovação ou distribuição oficial com a Korea Investment & Securities, KIS Developers ou true friend 한국투자 Open API. Toda a responsabilidade pelo uso deste projeto, incluindo instalação, configuração, chamadas de API, consulta de contas, execução de ordens, decisões de investimento e perdas, falhas, problemas de segurança resultantes, é do usuário. Antes de negociar de verdade, verifique diretamente a documentação oficial da Korea Investment & Securities e os valores de entrada.

Principais recursos

Chamadas baseadas em catálogo de API
- Fornece 8 grupos, 166 APIs REST
- Verificação de grupo/ID de API, caminho, método HTTP, candidatos a TR_ID, parâmetros de solicitação
- Fornece rótulos em coreano por parâmetro, guia de entrada, valores de exemplo, principais valores de código
- Lista completa: API_CATALOG.md
Ações domésticas
- Consulta de preço atual, cotações por período/diárias, ofertas, índices do setor, informações básicas
- Consulta de saldo, situação de ativos da conta de investimento, valor disponível para compra, quantidade disponível para venda
- Consulta de ordens, histórico de ordens, ordens passíveis de correção/cancelamento
Ações estrangeiras
- Suporte a códigos de mercado dos EUA, Japão, China, Hong Kong, Vietnã
- Consulta de preço atual, saldo, saldo atual com base em execuções, margem por moeda, valor disponível para compra
- Seleção automática de TR_ID de ordem com base no mercado/direção de compra/venda
Execução/Operação
- Suporte a transporte stdio, sse, streamable-http
- Configuração baseada em .env ou argumentos de linha de comando
- Preenchimento automático de número de conta, código do produto da conta, valores de autenticação
- Cache de token com base na chave do aplicativo e tipo de conta
- Rejeição padrão de parâmetros de solicitação desconhecidos
- Bloqueio padrão de APIs de ordem/correção/cancelamento

Padrões de segurança

APIs que alteram o estado da conta, como ordens/correções/cancelamentos, são bloqueadas por padrão.

KIS_ENABLE_TRADING=true

As APIs de alteração de estado só são executadas se você definir explicitamente o valor acima. Se você usar apenas APIs de consulta, não defina.

Requisitos

Python >= 3.13
uv

Instalação

A instalação deve ser feita com base em INSTALL.md. Ao configurar com LLM ou cliente MCP, leia este arquivo primeiro.

INSTALL.md contém o seguinte:

Instalação de dependências baseada em uv
Criação de .env e configuração de KIS_APP_KEY, KIS_APP_SECRET, KIS_CANO, KIS_ACNT_PRDT_CD
Exemplos de registro para Codex CLI, Claude Code, Claude Desktop, clientes MCP comuns
Configuração de KIS_MCP_TOOLSET=catalog para economia de contexto
Exemplo de call-kis-api para consulta de saldo, valor disponível para compra, preço atual

Preparação local rápida:

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

Em seguida, defina os valores abaixo em .env. Consulte INSTALL.md para explicações detalhadas dos valores e 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"

Execução

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

Também é possível configurar por argumentos de linha de comando.

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

Seleção 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

Exemplo de registro de cliente MCP:

Abaixo está um exemplo mínimo para clientes MCP comuns. Use INSTALL.md para comandos do Codex CLI, Claude Code, 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"
      }
    }
  }
}

Configuração de ferramentas MCP

Ferramentas de catálogo

Ferramenta	Descrição
`list-kis-api-specs`	Consulta de lista por grupo de API/palavra-chave
`get-kis-api-spec`	Verificação de caminho, candidatos a TR_ID, parâmetros de uma única API
`call-kis-api`	Chamada de API de catálogo com `group`, `api_type`, `params`

list-kis-api-specs retorna rótulos, valores de exemplo e principais valores de código dos parâmetros obrigatórios. get-kis-api-spec retorna informações de label, guide, examples, values, default, auto_fill de todos os parâmetros, para que o LLM possa ver imediatamente o formato de entrada necessário para a chamada.

call-kis-api realiza o seguinte processamento em comum:

Entrada automática de número de conta/código do produto da conta com base em variáveis de ambiente
Emissão e cache de token de autenticação
Construção de solicitações GET/POST
Parse para objeto quando alguns clientes MCP enviam params como string JSON
Seleção de TR_ID de ordem automaticamente identificável entre múltiplos TR_IDs
Aplicação de gate de segurança para APIs de alteração de estado
Rejeição padrão de parâmetros não presentes no catálogo

Ferramentas de conveniência

Funções de ações domésticas/estrangeiras usadas com frequência também são fornecidas como ferramentas MCP separadas.

Ferramenta	Descrição
`inquery-stock-price`	Consulta de preço atual de ações domésticas
`inquery-balance`	Consulta de saldo de ações domésticas
`inquery-order-list`	Consulta diária de ordens/execuções de ações domésticas
`inquery-order-detail`	Consulta de detalhes de ordem de ações domésticas
`inquery-stock-info`	Consulta de cotações diárias de ações domésticas
`inquery-stock-history`	Consulta de cotações por período de ações domésticas
`inquery-stock-ask`	Consulta de ofertas de ações domésticas
`inquery-stock-market`	Consulta de preço atual de setor/índice doméstico
`inquery-stock-basic-info`	Consulta de informações básicas de ações domésticas
`inquery-overseas-stock-price`	Consulta de preço atual de ações estrangeiras
`order-stock`	Ordem de compra/venda de ações domésticas
`order-overseas-stock`	Ordem de compra/venda de ações estrangeiras

As ferramentas de ordem também não são executadas sem KIS_ENABLE_TRADING=true.

Otimização de carregamento de ferramentas

O cliente MCP carrega nomes de ferramentas, descrições e esquemas de entrada no contexto ao conectar ao servidor. Quanto mais ferramentas de conveniência forem expostas, maior será o uso de contexto no início da conversa. Portanto, se necessário, você pode usar o modo leve que expõe apenas as 3 ferramentas de catálogo.

KIS_MCP_TOOLSET=catalog uv run python server.py

Valor	Número de ferramentas expostas	Ferramentas expostas	Uso
`full`	15	Ferramentas de catálogo + todas as ferramentas de conveniência	Compatível com o comportamento existente
`catalog`	3	`list-kis-api-specs`, `get-kis-api-spec`, `call-kis-api`	Baixo uso de contexto

O modo catalog é um modo para reduzir a carga de esquemas de ferramentas MCP. Ele oculta as ferramentas de conveniência, mas as 166 APIs ainda podem ser chamadas via call-kis-api. Você pode encontrar a API necessária com list-kis-api-specs e consultar os parâmetros detalhados necessários com get-kis-api-spec conforme necessário.

Fluxo de uso recomendado:

Pesquise a API com list-kis-api-specs.
Verifique parâmetros obrigatórios, valores de exemplo e valores de código com get-kis-api-spec.
Chame a API real com call-kis-api.

Na configuração do cliente MCP, basta adicionar a variável de ambiente.

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

Se quiser expor ferramentas de conveniência usadas com frequência diretamente na lista de ferramentas, use o valor padrão full.

Exemplo de `call-kis-api`

Preço atual de ações domésticas:

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

Saldo de ações estrangeiras:

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

Saldo atual com base em execuções de ações estrangeiras:

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

Valor disponível para compra de ações estrangeiras:

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

Principais grupos de API

Grupo	Descrição	Número de APIs
`auth`	Autenticação	2
`domestic_stock`	Ações domésticas	74
`overseas_stock`	Ações estrangeiras	34
`domestic_bond`	Títulos domésticos	14
`domestic_futureoption`	Futuros e opções domésticos	20
`overseas_futureoption`	Futuros e opções estrangeiros	19
`elw`	ELW	1
`etfetn`	ETF/ETN	2

O guia completo de IDs de API, caminhos, TR_IDs e parâmetros obrigatórios está organizado em API_CATALOG.md.

Variáveis de ambiente

Nome	Descrição	Valor padrão
`KIS_APP_KEY`	Chave do aplicativo KIS	-
`KIS_APP_SECRET`	Chave secreta KIS	-
`KIS_ACCOUNT_TYPE`	`REAL` ou `VIRTUAL`	-
`KIS_CANO`	Primeiros 8 dígitos do número da conta	-
`KIS_ACNT_PRDT_CD`	Código do produto da conta	`01`
`KIS_TOKEN_FILE`	Arquivo de cache de token	`token.json`
`KIS_ENABLE_TRADING`	Ativação de APIs de ordem/correção/cancelamento	Desativado
`KIS_MCP_TOOLSET`	Escopo de exposição de ferramentas MCP (`full`, `catalog`)	`full`
`KIS_MCP_LOG_LEVEL`	Nível de log	`INFO`
`MCP_TYPE`	`stdio`, `sse`, `streamable-http`	`stdio`
`MCP_HOST`	Host HTTP/SSE	`127.0.0.1`
`MCP_PORT`	Porta HTTP/SSE	`8000`
`MCP_PATH`	Caminho HTTP/SSE	`/mcp`

Desenvolvimento/Validação

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

Contribuidores

Colaboradores de IA foram excluídos da lista de contribuidores.

Contributor	Role
migusdn	Maintainer
mickeykim70	Contributor
haesam5060-arch	Contributor

Licença

MIT

Korea Investment & Securities (KIS) REST API

Documentação