OpLab MCP Server

OpLab MCP Server

  

Servidor MCP (Model Context Protocol) para integração com as APIs do OpLab, permitindo que agentes de IA acessem dados do mercado financeiro brasileiro.

📦 Ferramentas Disponíveis

| Ferramenta | Descrição | |------------|-----------| | get_stock_info | Informações detalhadas de ações (preço, volume, fundamentalistas) | | get_historical_data | Dados históricos com múltiplas resoluções (1d, 1h, etc) | | get_options_chain | Cadeia de opções completa com strikes e vencimentos | | get_stock_quote | Cotações em tempo real de múltiplos ativos | | search_instruments | Busca de ações, opções, fundos e índices | | get_market_status | Status do mercado (aberto/fechado) | | get_interest_rates | Taxas SELIC e CDI atualizadas |

🔧 Instalação

Requisitos

• Docker e Docker Compose OU
• Python 3.11+
• Token de acesso OpLab (obtenha aqui)

Opção 1: Docker (Recomendado)

# 1. Clone o repositório
git clone https://github.com/seu-usuario/oplab-mcp.git
cd oplab-mcp

# 2. Build da imagem
docker build -t oplab-mcp:latest .

# 3. Execute o container
docker run -d \
  --name oplab-mcp \
  -p 8000:8000 \
  -e OPLAB_ACCESS_TOKEN=seu_token_aqui \
  -e SERVER_MODE=http \
  --restart unless-stopped \
  oplab-mcp:latest

Opção 2: Python local

# 1. Clone e instale dependências
git clone https://github.com/seu-usuario/oplab-mcp.git
cd oplab-mcp
pip install -r requirements.txt

# 2. Configure o token
export OPLAB_ACCESS_TOKEN=seu_token_aqui

# 3. Execute em modo HTTP
export SERVER_MODE=http
python server.py

# OU em modo stdio (para uso local)
python server.py

⚙️ Configuração

Variáveis de Ambiente

| Variável | Descrição | Padrão | Obrigatório | |----------|-----------|--------|-------------| | OPLAB_ACCESS_TOKEN | Token de API do OpLab | - | Sim | | SERVER_MODE | Modo de execução: http ou stdio | stdio | Não | | SERVER_PORT | Porta HTTP (apenas modo http) | 8000 | Não | | SERVER_HOST | Host HTTP (apenas modo http) | 0.0.0.0 | Não |

Modos de Operação

🌐 Modo HTTP (para agentes remotos)

Expõe o servidor via HTTP com Server-Sent Events (SSE):

docker run -d \
  --name oplab-mcp \
  -p 8000:8000 \
  -e OPLAB_ACCESS_TOKEN=seu_token \
  -e SERVER_MODE=http \
  oplab-mcp:latest

Endpoint MCP: http://localhost:8000/mcp

💻 Modo stdio (para agentes locais)

Executa via stdio para integração direta:

docker run -i --rm \
  -e OPLAB_ACCESS_TOKEN=seu_token \
  -e SERVER_MODE=stdio \
  oplab-mcp:latest

🤖 Integração com Agentes

Claude Desktop

Arquivo: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "oplab": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Ou com Docker (stdio):

{
  "mcpServers": {
    "oplab": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "OPLAB_ACCESS_TOKEN=seu_token",
        "-e", "SERVER_MODE=stdio",
        "oplab-mcp:latest"
      ]
    }
  }
}

📖 Exemplos de Uso

Depois de configurado, você pode interagir com seu agente de IA:

👤 "Me mostre informações sobre PETR4"
🤖 [usa get_stock_info] Retorna preço, volume, variação...

👤 "Busque o histórico de VALE3 nos últimos 30 dias"
🤖 [usa get_historical_data] Retorna série histórica...

👤 "Quais opções estão disponíveis para ITUB4?"
🤖 [usa get_options_chain] Lista calls e puts com strikes...

👤 "O mercado está aberto agora?"
🤖 [usa get_market_status] Informa status atual...

👤 "Busque empresas de tecnologia"
🤖 [usa search_instruments] Lista empresas do setor...

🛠️ Desenvolvimento

Estrutura do Projeto

oplab-mcp/
├── server.py             # Servidor MCP principal
├── requirements.txt      # Dependências Python
├── Dockerfile            # Imagem Docker
└── README.md             # Este arquivo

Comandos Úteis

# Ver logs do container
docker logs -f oplab-mcp

# Reiniciar servidor
docker restart oplab-mcp

# Parar e remover
docker stop oplab-mcp && docker rm oplab-mcp

# Rebuild após mudanças
docker build -t oplab-mcp:latest . && docker restart oplab-mcp

Token inválido

Erro: OPLAB_ACCESS_TOKEN não configurado

Solução: Certifique-se de passar o token via -e OPLAB_ACCESS_TOKEN=...

Agente não conecta

1. Verifique se o servidor está rodando: docker ps | grep oplab-mcp
2. Teste o endpoint: curl http://localhost:8000/mcp
3. Verifique a URL na configuração do agente
4. Reinicie o agente após configurar

Endpoints Utilizados

• /market/stocks/{symbol} - Informações de ações
• /market/historical/{symbol}/{resolution} - Dados históricos
• /market/options/{symbol} - Cadeia de opções
• /market/quote - Cotações em tempo real
• /market/instruments/search - Busca de instrumentos
• /market/status - Status do mercado
• /market/interest_rates - Taxas de juros

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para:

1. Fazer fork do projeto
2. Criar uma branch para sua feature (git checkout -b feature/MinhaFeature)
3. Commit suas mudanças (git commit -m 'Adiciona MinhaFeature')
4. Push para a branch (git push origin feature/MinhaFeature)
5. Abrir um Pull Request

📝 License

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

🔗 Links Úteis

• FastMCP Documentation
• OpLab API Docs

💬 Suporte

Para dúvidas ou problemas:

• Abra uma issue no GitHub
• Consulte a documentação do OpLab

---

Feito com ❤️ para a comunidade de desenvolvedores brasileiros