🇧🇷 big-mcp-b3

MCP Server completo para dados da B3 — cotações, FIIs, proventos, fundamentos, opções e índices.

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

{
  "mcpServers": {
    "big-mcp-b3": {
      "command": "npx",
      "args": ["-y", "big-mcp-b3"],
      "env": {
        "BRAPI_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Cursor

Adicione ao .cursor/mcp.json:

{
  "servers": {
    "big-mcp-b3": {
      "command": "npx",
      "args": ["-y", "big-mcp-b3"],
      "env": {
        "BRAPI_TOKEN": "seu-token-aqui"
      }
    }
  }
}

VS Code

Crie .vscode/mcp.json:

{
  "servers": {
    "big-mcp-b3": {
      "command": "npx",
      "args": ["-y", "big-mcp-b3"],
      "env": {
        "BRAPI_TOKEN": "seu-token-aqui"
      }
    }
  }
}

Hermes

hermes mcp add big-mcp-b3 -- npx -y big-mcp-b3

Desenvolvimento Local

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

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 para detalhes.

🤝 Contribuindo

Contribuições são bem-vindas! Veja CONTRIBUTING.md para diretrizes.

📧 Contato

• GitHub: @danielvm-git
• Issues: GitHub Issues

---

Feito com ❤️ para investidores brasileiros