Content
# 🇧🇷 big-mcp-b3
**MCP Server completo para dados da B3** — cotações, FIIs, proventos, fundamentos, opções e índices.
[](https://www.npmjs.com/package/big-mcp-b3)
[](LICENSE)
[](https://modelcontextprotocol.io)
## ✨ Features
- **10 tools** para dados do mercado financeiro brasileiro
- **Sem chave de API obrigatória** — funciona imediatamente com brapi.dev (gratuita)
- **TypeScript moderno** — tipagem forte, async/await
- **Zero dependências pesadas** — apenas MCP SDK + Zod
- **Compatível** com Claude Desktop, Cursor, VS Code, Hermes
## 🛠️ Tools Disponíveis
| Tool | Descrição | API |
|------|-----------|-----|
| `cotacao_ativo` | Cotação em tempo real | brapi.dev |
| `historico_ativo` | Histórico de preços | brapi.dev |
| `proventos_ativo` | Dividendos, JCP, bonificações | brapi.dev |
| `fiis_lista` | Lista de fundos imobiliários | CVM + brapi.dev |
| `fii_detalhes` | Detalhes de um FII específico | brapi.dev |
| `fundamentus_ativo` | Fundamentalismo (P/L, ROE, margens) | fundamentus.com.br |
| `indices_b3` | Ibovespa, IFIX, IDIV, SMLL, etc. | brapi.dev |
| `opcoes_ativo` | Cadeia de opções (calls e puts) | brapi.dev |
| `comparar_ativos` | Compara múltiplos ativos lado a lado | brapi.dev |
## 🚀 Quick Start
### Claude Desktop
Adicione ao `claude_desktop_config.json`:
```json
{
"mcpServers": {
"big-mcp-b3": {
"command": "npx",
"args": ["-y", "big-mcp-b3"],
"env": {
"BRAPI_TOKEN": "seu-token-aqui"
}
}
}
}
```
### Cursor
Adicione ao `.cursor/mcp.json`:
```json
{
"servers": {
"big-mcp-b3": {
"command": "npx",
"args": ["-y", "big-mcp-b3"],
"env": {
"BRAPI_TOKEN": "seu-token-aqui"
}
}
}
}
```
### VS Code
Crie `.vscode/mcp.json`:
```json
{
"servers": {
"big-mcp-b3": {
"command": "npx",
"args": ["-y", "big-mcp-b3"],
"env": {
"BRAPI_TOKEN": "seu-token-aqui"
}
}
}
}
```
### Hermes
```bash
hermes mcp add big-mcp-b3 -- npx -y big-mcp-b3
```
### Desenvolvimento Local
```bash
# Clone o repositório
git clone https://github.com/danielvm-git/big-mcp-b3.git
cd big-mcp-b3
# Instale dependências
npm install
# Execute em modo desenvolvimento
npm run dev
# Build para produção
npm run build
```
## 📖 Exemplos de Uso
Após configurar o MCP server, faça perguntas em linguagem natural:
> **Cotação:** "Qual a cotação atual de PETR4?"
> **Histórico:** "Mostre o histórico de VALE3 nos últimos 3 meses"
> **Proventos:** "Quais foram os dividendos pagos por TAEE11?"
> **FIIs:** "Liste os FIIs de shoppings"
> **Índices:** "Como está o Ibovespa hoje?"
> **Opções:** "Quais são as opções de PETR4 com vencimento em 2026?"
> **Comparação:** "Compare PETR4 com VALE3 e ITUB4"
## ⚙️ Configuração
### Variáveis de Ambiente
| Variável | Obrigatória | Descrição |
|----------|------------|-----------|
| `BRAPI_TOKEN` | Não | Token da brapi.dev (gratuito, 100 req/dia) |
| `REQUEST_TIMEOUT` | Não | Timeout das requisições em ms (padrão: 30000) |
| `MAX_RETRIES` | Não | Número máximo de retentativas (padrão: 3) |
### Obtendo Token da brapi.dev
1. Acesse [brapi.dev](https://brapi.dev)
2. Crie uma conta gratuita
3. Copie seu token do dashboard
4. Adicione ao `.env` ou na configuração do MCP
**Nota:** O server funciona sem token (com limite de requisições).
## 📊 Dados Disponíveis
### Ações
- Cotação em tempo real
- Histórico de preços (1d a 10y)
- Dividendos e JCP
- Opções (calls e puts)
### Fundos Imobiliários
- Lista completa via CVM
- Cotação e variação
- Proventos pagos
### Índices
- Ibovespa (^BVSP)
- IFIX (^IFIX)
- IDIV (^IDIV)
- SMLL (^SMLL)
- E mais...
## 🔧 Desenvolvimento
### Estrutura do Projeto
```
big-mcp-b3/
├── src/
│ ├── index.ts # Entry point
│ ├── types/ # Definições de tipos
│ ├── services/ # Serviços de API
│ │ ├── brapi.ts # brapi.dev
│ │ └── cvm.ts # CVM dados abertos
│ └── tools/ # Tools MCP
│ ├── cotacao.ts # Cotação
│ ├── historico.ts # Histórico
│ ├── proventos.ts # Proventos
│ ├── fiis.ts # FIIs
│ ├── fundamentus.ts# Fundamentos
│ ├── indices.ts # Índices
│ ├── opcoes.ts # Opções
│ └── comparar.ts # Comparação
├── tests/
├── docs/
├── package.json
├── tsconfig.json
└── README.md
```
### Comandos
```bash
npm run dev # Executa em modo desenvolvimento
npm run build # Compila TypeScript
npm run start # Executa versão compilada
npm test # Executa testes
```
## 📝 Licença
MIT — veja [LICENSE](LICENSE) para detalhes.
## 🤝 Contribuindo
Contribuições são bem-vindas! Veja [CONTRIBUTING.md](CONTRIBUTING.md) para diretrizes.
## 📧 Contato
- GitHub: [@danielvm-git](https://github.com/danielvm-git)
- Issues: [GitHub Issues](https://github.com/danielvm-git/big-mcp-b3/issues)
---
**Feito com ❤️ para investidores brasileiros**
