KOSPI/KOSDAQ Stock Server
Fornece dados de ações da KOSPI/KOSDAQ, incluindo consulta de ticker, OHLCV, capitalização de mercado e dados fundamentais.
GitHub
73
Experimente este MCPPatrocinadoDocumentação
kospi-kosdaq-stock-server
Um servidor MCP que fornece dados de ações KOSPI/KOSDAQ do KRX Data Marketplace.
Novidades na v0.3.0
Desde 27 de dezembro de 2024, o KRX Data Marketplace exige login com Kakao/Naver para acesso aos dados. Esta versão implementa:
- Integração direta com a API do KRX com login OAuth do Kakao
- Navegador headless baseado em Playwright para autenticação
- Gerenciamento automático de sessão com timeout de 4 horas e re-login automático
- Sem dependência de pykrx para funcionalidades principais
Recursos
- Consultar símbolos de ticker e nomes de KOSPI/KOSDAQ
- Recuperar dados OHLCV (Abertura/Máxima/Mínima/Fechamento/Volume) para ações
- Recuperar dados de capitalização de mercado
- Recuperar dados fundamentais (P/L/PVP/Rendimento de Dividendos)
- Recuperar volume de negociação por tipo de investidor (institucional, estrangeiro, individual)
- Recuperar dados OHLCV de índices (índices KOSPI, KOSDAQ)
Requisitos
- Python 3.10+
- Conta Kakao (2FA deve estar desativado)
- Navegador Playwright Chromium
Variáveis de Ambiente
# Required: Kakao login credentials
KAKAO_ID=your_kakao_id
KAKAO_PW=your_kakao_password
Importante: Sua conta Kakao deve ter a verificação em duas etapas (2FA) desativada. No primeiro login, você pode precisar aprovar a solicitação de login via KakaoTalk.
Instalação
Pré-requisitos
# Install Playwright and Chromium browser
pip install playwright
playwright install chromium
Instalação via Smithery
npx -y @smithery/cli install @dragon1086/kospi-kosdaq-stock-server --client claude
Instalação Manual
# Create and activate a virtual environment
uv venv .venv
source .venv/bin/activate # On Unix/macOS
# .venv\Scripts\activate # On Windows
# Install the package
uv pip install kospi-kosdaq-stock-server
# Install Playwright browser
playwright install chromium
Configuração para Claude Desktop
macOS
- Abra o arquivo de configuração:
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
- Adicione a configuração do servidor:
{
"mcpServers": {
"kospi-kosdaq": {
"command": "uvx",
"args": ["kospi_kosdaq_stock_server"],
"env": {
"KAKAO_ID": "your_kakao_id",
"KAKAO_PW": "your_kakao_password"
}
}
}
}
Windows
-
Abra o arquivo de configuração em
%APPDATA%/Claude/claude_desktop_config.json -
Adicione a mesma configuração acima
-
Reinicie o Claude Desktop
Ferramentas Disponíveis
load_all_tickers
Carrega todos os símbolos de ticker e nomes para KOSPI e KOSDAQ.
- Nenhum argumento necessário
- Retorna: Dicionário mapeando códigos de ticker para nomes de ações
get_stock_ohlcv
Recupera dados OHLCV (Abertura/Máxima/Mínima/Fechamento/Volume) para uma ação específica.
fromdate(string, obrigatório): Data de início (AAAAMMDD)todate(string, obrigatório): Data de fim (AAAAMMDD)ticker(string, obrigatório): Símbolo do ticker da ação (ex.: "005930")adjusted(booleano, opcional): Usar preços ajustados (padrão: True)
get_stock_market_cap
Recupera dados de capitalização de mercado para uma ação específica.
fromdate(string, obrigatório): Data de início (AAAAMMDD)todate(string, obrigatório): Data de fim (AAAAMMDD)ticker(string, obrigatório): Símbolo do ticker da ação
get_stock_fundamental
Recupera dados fundamentais (P/L/PVP/Rendimento de Dividendos) para uma ação específica.
fromdate(string, obrigatório): Data de início (AAAAMMDD)todate(string, obrigatório): Data de fim (AAAAMMDD)ticker(string, obrigatório): Símbolo do ticker da ação
get_stock_trading_volume
Recupera volume de negociação por tipo de investidor para uma ação específica.
fromdate(string, obrigatório): Data de início (AAAAMMDD)todate(string, obrigatório): Data de fim (AAAAMMDD)ticker(string, obrigatório): Símbolo do ticker da açãodetail(booleano, opcional): Se verdadeiro, retorna 12 tipos de investidores; se falso (padrão), retorna 5 tipos agregados
get_index_ohlcv
Recupera dados OHLCV para índices de mercado.
fromdate(string, obrigatório): Data de início (AAAAMMDD)todate(string, obrigatório): Data de fim (AAAAMMDD)ticker(string, obrigatório): Ticker do índice (ex.: "1001" para KOSPI, "2001" para KOSDAQ)freq(string, opcional): Frequência - "d" (diária), "m" (mensal), "y" (anual). Padrão: "d"
Recursos Disponíveis
stock://tickers
Retorna todos os símbolos de ticker e nomes de KOSPI/KOSDAQ.
stock://index-tickers
Retorna informações de tickers de índices:
- KOSPI: 1001, KOSPI 200: 1028, KOSPI 100: 1034, KOSPI 50: 1035
- KOSDAQ: 2001, KOSDAQ 150: 2203
stock://data-sources
Retorna o status atual da fonte de dados.
Suporte a Docker
Usando Docker Compose
# Build and run
docker-compose up -d
# View logs
docker-compose logs -f
Variáveis de Ambiente para Docker
Crie um arquivo .env:
KAKAO_ID=your_kakao_id
KAKAO_PW=your_kakao_password
Solução de Problemas
Popup "Notificação de login do KakaoTalk"
No primeiro login, o Kakao pode exigir aprovação via KakaoTalk:
- Execute com
headless=Falsepara ver o navegador - Aprove o login no KakaoTalk
- Os cookies serão salvos para sessões futuras
401 Não Autorizado / Sessão Expirada
A sessão expira após ~4 horas. O servidor renova automaticamente, mas se falhar:
- Exclua
~/.krx_session.json - Reinicie o servidor
Ambiente Headless Linux
# Install required packages on Ubuntu/Debian
apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libgbm1 libasound2
Arquitetura
┌─────────────────────────────────────────────────────┐
│ MCP Server (FastMCP) │
│ kospi_kosdaq_stock_server.py │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ KRXDataClient │
│ - get_market_ohlcv() │
│ - get_market_cap() │
│ - get_market_fundamental() │
│ - get_market_trading_volume_by_date() │
│ - get_index_ohlcv() │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ KakaoAuthManager │
│ - Playwright headless browser │
│ - Kakao OAuth login │
│ - Session cookie management │
│ - Auto re-login on session expiry (4h) │
└──────────────────────┬──────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ KRX Data Marketplace │
│ data.krx.co.kr │
└─────────────────────────────────────────────────────┘
Limitações Conhecidas
- Contas Kakao com 2FA ativado não são suportadas
- O primeiro login pode exigir aprovação via KakaoTalk
- Validade da sessão: ~4 horas (renovação automática suportada)
- Login com Naver ainda não implementado
Exemplo de Uso
Human: Please load all available stock tickers.
Assistant: I'll load all KOSPI and KOSDAQ stock tickers.
> Using tool 'load_all_tickers'...
Successfully loaded 2,738 stock tickers.
Human: Show me Samsung Electronics' stock data for December 2024.
Assistant: I'll retrieve Samsung Electronics' (005930) OHLCV data.
> Using tool 'get_stock_ohlcv'...
Date Open High Low Close Volume
2024-12-20 53,800 54,200 53,500 53,900 8,234,521
2024-12-19 54,000 54,300 53,700 53,800 7,123,456
...
Licença
Licença MIT
Contribuição
Issues e pull requests são bem-vindos!
Histórico de Versões
v0.3.0 (2025-01-04)
- Quebra: Removida dependência de pykrx para funcionalidades principais
- Adicionada integração direta com KRX Data Marketplace via OAuth do Kakao
- Adicionada autenticação headless baseada em Playwright
- Adicionado gerenciamento automático de sessão
- Adicionado suporte a OHLCV de índices
v0.2.x
- Implementação baseada em pykrx (descontinuada devido ao requisito de login do KRX)