MCP Server para B3: Como Conectar Claude e ChatGPT aos Dados da Bolsa Brasileira

O que é o Model Context Protocol e por que ele importa

Antes do MCP, cada integração entre um LLM e uma fonte de dados exigia código customizado: uma função Python, um plugin proprietário ou um agent framework específico. O resultado era fragmentação, pouco reuso e dificuldade para auditar o que o modelo fazia com a ferramenta. O protocolo resolve isso com três componentes: um cliente (Claude Desktop, Cursor, Claude Code), um servidor (processo local ou remoto que expõe ferramentas) e um canal de comunicação JSON-RPC sobre stdio ou HTTP.

A especificação é publicada em modelcontextprotocol.io e o anúncio original da Anthropic está em anthropic.com/news/model-context-protocol. A adoção cresceu rapidamente: Cursor, Cline, Zed e o próprio Claude Code passaram a suportar o protocolo durante 2025. Hoje, qualquer provedor de dados que publique um servidor MCP fica automaticamente acessível em todo esse ecossistema.

Para o mercado brasileiro, isso representa uma mudança concreta na forma como análise fundamentalista pode ser consumida. Até 2024, extrair o P/L de uma ação dentro de uma conversa com IA exigia copiar e colar números de uma planilha ou de um site de análise. Com um mcp financeiro brasil rodando, a pergunta "qual o ROE da WEGE3?" é respondida com dados oficiais da CVM processados pela API bolsai, sem intervenção manual.

Casos de uso: análise fundamentalista, screening e research assistidos por IA

O valor prático do bolsai-mcp aparece em cenários concretos de research. Três padrões cobrem a maioria dos usos observados entre quem integra o servidor ao Claude Desktop.

Análise fundamentalista guiada

O investidor lê um release trimestral e quer contexto imediato: como os números publicados se comparam aos dos últimos trimestres, quais múltiplos o mercado está precificando, que métricas ficaram fora da norma setorial. Um prompt como "Claude, explique o ROE atual do ITUB4 no contexto dos últimos 8 trimestres e compare com BBAS3 e BBDC4" aciona chamadas encadeadas a get_fundamentals, get_fund_history e compare_stocks. A resposta combina os números brutos com a narrativa textual que um analista júnior levaria uma tarde para montar.

Screening por critérios fundamentalistas

Filtros quantitativos tradicionalmente exigem dashboards. Com o mcp server b3, eles viram pergunta: "FIIs de logística com DY acima de 9% e P/VP abaixo de 1". O modelo traduz os critérios em parâmetros da ferramenta screen_stocks ou get_fii_data, executa a consulta e devolve uma tabela ordenada. O resultado é reprodutível, porque todas as decisões de filtragem ficam registradas na conversa.

Research comparativo setorial

Comparar fundamentos entre os cinco maiores bancos da B3 é um pedido frequente. O Claude, com acesso ao bolsai-mcp, resolve isso em um turno: chama compare_stocks com uma lista de tickers, recebe 27 indicadores para cada um e produz uma análise textual focada nos pontos relevantes (margem financeira, índice de Basileia, ROE, provisões). A profundidade dos dados vem da API; a síntese analítica vem do modelo.

Instalação do bolsai-mcp

O servidor é distribuído como pacote Python chamado bolsai-mcp, publicado no PyPI. A instalação mais direta usa uvx, o executor de pacotes do gerenciador uv, que cria um ambiente isolado automaticamente e não deixa rastros no sistema. O requisito mínimo é Python 3.10.

# Opção 1: via uvx (recomendada, sem instalação global)
uvx bolsai-mcp

# Opção 2: via pip, em um virtualenv
pip install bolsai-mcp

# Verificar versão instalada
bolsai-mcp --version

A autenticação é feita pela variável de ambiente BOLSAI_API_KEY. A chave sai do dashboard em usebolsai.com/dashboard após o cadastro com login Google. O plano gratuito inclui 200 requisições por dia, suficiente para uso experimental e para a maioria das sessões de research individuais.

Quem preferir não instalar nada localmente pode consultar a documentação completa do bolsai-mcp na página /mcp, que traz instruções alternativas para Claude Code, Cursor e clientes MCP remotos. A configuração JSON apresentada na próxima seção é equivalente entre todos eles.

Configuração no Claude Desktop

O Claude Desktop lê servidores MCP a partir do arquivo claude_desktop_config.json. A localização varia por sistema operacional:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

O conteúdo do arquivo declara um ou mais servidores. Para o bolsai-mcp, a configuração mínima é a seguinte:

{
  "mcpServers": {
    "bolsai": {
      "command": "uvx",
      "args": ["bolsai-mcp"],
      "env": {
        "BOLSAI_API_KEY": "sk_sua_chave_aqui"
      }
    }
  }
}

Após salvar o arquivo, o Claude Desktop precisa ser reiniciado. Um ícone de ferramenta aparece no canto inferior do campo de mensagem quando o servidor está ativo, permitindo inspecionar as ferramentas expostas. O protocolo exige consentimento explícito na primeira chamada: o usuário autoriza cada ferramenta individualmente.

Primeira consulta: "Claude, qual o P/L do ITUB4?"

A validação mais rápida da integração é uma pergunta simples sobre um ticker líquido. O prompt abaixo dispara uma única chamada à ferramenta get_fundamentals e o Claude responde com o número extraído do JSON retornado.

# Prompt do usuário
Claude, qual o P/L do ITUB4 hoje?

# Claude chama: get_fundamentals({"ticker": "ITUB4"})
# Resposta da ferramenta (trecho):
{
  "ticker": "ITUB4",
  "corporate_name": "ITAU UNIBANCO HOLDING S.A.",
  "pl": 9.87,
  "pvp": 2.08,
  "roe": 21.32,
  "net_margin": 31.4,
  "market_cap": 362500000000,
  "reference_date": "2025-12-31"
}

# Resposta textual do Claude
O P/L atual do ITUB4 é 9.87, calculado
com TTM a partir do balanço de 31/12/2025. O ROE é 21.32%
e o múltiplo P/VP, 2.08.

O campo pl vem do endpoint /fundamentals/ITUB4 e é calculado com lucro líquido TTM e preço de fechamento mais recente. A metodologia segue o detalhamento descrito no post P/L: como calcular preço sobre lucro com API em Python, que explica por que a conta CVM 3.11 (resultado consolidado) é escolhida como numerador.

Screening conversacional: encontrar ações com critérios fundamentalistas

Screening é o caso em que a integração ia análise ações via MCP mais se destaca. Em vez de preencher formulário de filtros em uma plataforma, o usuário formula o critério em linguagem natural e o modelo monta a chamada apropriada. O exemplo abaixo mostra a tradução automática de um pedido comum.

# Prompt do usuário
Quais as 10 ações da B3 com maior ROE e P/L abaixo de 12?

# Claude chama: screen_stocks(
#   {"roe_min": 15, "pl_max": 12, "sort": "roe_desc", "limit": 10}
# )

# Resposta resumida da ferramenta
Ticker    P/L    ROE     Setor
BBSE3     9.10   35.2%   Seguros
ITUB4     9.87   21.3%   Bancos
VIVT3     8.45   18.7%   Telecom
BBAS3     4.56   21.3%   Bancos
CPLE6     5.89   18.5%   Utilities
TAEE11    8.23   19.8%   Transmissão
EGIE3     9.12   17.4%   Geração
CMIG4    10.20   16.8%   Utilities
PSSA3     7.85   22.1%   Seguros
RENT3    11.40   15.2%   Locação

# Claude (texto):
Dez empresas cumprem os critérios. O grupo concentra
setores regulados (utilities, transmissão) e financeiras
com ROE alto, padrão comum em screenings de valor na B3.

Critérios adicionais são acrescentados no próprio prompt. "Exclua bancos e mantenha apenas empresas com dívida líquida sobre EBITDA abaixo de 2x" resulta em nova chamada com parâmetros sector_exclude e net_debt_ebitda_max. O conjunto completo de filtros aceito pelo screen_stocks está documentado em /docs.

Análise comparativa de FIIs via linguagem natural

Fundos imobiliários têm cobertura dedicada no bolsai-mcp por meio da ferramenta get_fii_data. O uso típico envolve comparação de múltiplos entre fundos do mesmo segmento.

# Prompt do usuário
Compare HGLG11, XPLG11 e VILG11. DY dos últimos
12 meses, P/VP e número de imóveis.

# Claude chama get_fii_data três vezes (uma por ticker)

# Resultado consolidado:
Ticker     P/VP    DY 12m    Imóveis    Segmento
HGLG11     0.94    8.7%      21         Logística
XPLG11     0.88    9.4%      15         Logística
VILG11     1.02    8.1%      18         Logística

# Análise do Claude:
XPLG11 apresenta o maior dividend yield 12m (9.4%)
combinado com o menor P/VP (0.88), indicando desconto
relativo frente aos pares. HGLG11 tem o maior número
de imóveis, característica defensiva para diversificação
geográfica da carteira de lastro.

Para research mais profundo sobre FIIs, o post API de fundos imobiliários em Python detalha os endpoints REST subjacentes, que o servidor MCP consome internamente.

Dados macroeconômicos (Selic, CDI, IPCA) em prompts contextuais

Decisões de alocação entre renda fixa e renda variável dependem do cenário macro. A ferramenta get_macro_data expõe séries do Banco Central: Selic, CDI, IPCA e câmbio USD/BRL. Um exemplo frequente combina macro com fundamentos em um único prompt.

# Prompt do usuário
Com a Selic atual, um DY de 8% em ações de utilities
ainda faz sentido ou é melhor ficar no CDI?

# Claude chama duas ferramentas em sequência:
# 1. get_macro_data({"indicator": "selic"})  -> 14.25%
# 2. get_macro_data({"indicator": "cdi"})    -> 14.15%

# Análise do Claude:
Selic em 14.25% a.a. e CDI em 14.15%. Um DY nominal
de 8% em utilities perde 6.15 pontos percentuais para
o CDI em retorno corrente. A comparação, porém, ignora
dois fatores: (1) ganho de capital potencial em ciclo
de corte de juros, (2) crescimento do dividendo por
reajuste tarifário anual vinculado ao IPCA. Utilities
com contratos indexados ao IPCA tendem a ter fluxo
real positivo mesmo em cenários de juro alto.

Este é o tipo de análise que combina dados quantitativos com raciocínio textual, território onde um llm bolsa brasileira com acesso a ferramentas supera tanto um chatbot sem dados quanto um dashboard estático sem interpretação.

10 ferramentas do bolsai-mcp: referência

O servidor expõe dez ferramentas nomeadas. Cada uma mapeia para um ou mais endpoints da API bolsai e segue o schema JSON-RPC definido pela especificação MCP. A tabela abaixo resume os inputs e outputs principais.

Prompt composto: "compare o P/L de WEGE3 com o setor"

Pedidos que envolvem comparação setorial exigem várias chamadas encadeadas. O Claude decide sozinho a ordem das invocações. O padrão abaixo é comum quando o modelo combina get_fundamentals, list_tickers e compare_stocks.

# Prompt do usuário
Compare o P/L de WEGE3 com a média do setor industrial.
WEGE3 está cara ou barata no contexto?

# Chamadas executadas pelo Claude:
# 1. get_fundamentals({"ticker": "WEGE3"})
#    -> pl=28.46, roe=39.5%, net_margin=17.2%

# 2. list_tickers({"sector": "Industrials"})
#    -> [EMBR3, WEGE3, ROMI3, KEPL3, TUPY3, ...]

# 3. compare_stocks({"tickers": ["EMBR3", "ROMI3",
#    "KEPL3", "TUPY3", "RAPT4"]})
#    -> P/L médio do grupo: 12.8

# Resposta do Claude:
WEGE3 negocia a P/L 28.46 contra média setorial de 12.8.
O prêmio de 2.2x é historicamente consistente: a empresa
combina ROE de 39.5% com margem líquida de 17.2%, muito
acima dos pares industriais. O mercado precifica
qualidade operacional superior, não sobrepreço por
especulação. Para uma tese de entrada, faz sentido
comparar o múltiplo atual com a média histórica da
própria WEGE3 em vez da média setorial.

Limitações atuais e troubleshooting

Duas categorias de problema aparecem com frequência na primeira configuração. A primeira é de autenticação, a segunda é de ambiente Python.

Erro: API key inválida

Mensagem típica no log do Claude Desktop: 401 Unauthorized. O diagnóstico costuma ser um dos três: a chave tem espaço invisível no início ou fim (copiar do dashboard com duplo-clique resolve), a variável BOLSAI_API_KEY foi definida no shell mas o Claude Desktop foi iniciado antes da variável ser exportada, ou a chave foi revogada no dashboard e não regenerada.

Erro: rate limit exceeded

Mensagem 429 Too Many Requests indica que o limite diário foi atingido. No plano gratuito, são 200 requisições em 24h. Uma única sessão de research com muitas chamadas encadeadas consome rápido essa cota. A solução é o plano Pro (R$29/mês, 10.000 req/dia) ou esperar a janela resetar. O header X-RateLimit-Remaining retornado pela API mostra quanto resta.

Erro: uvx command not found

Acontece quando o gerenciador uv não está instalado ou não está no PATH. A correção é rodar curl -LsSf https://astral.sh/uv/install.sh | sh em sistemas Unix ou seguir o instalador oficial no Windows. Uma alternativa imediata é substituir "command": "uvx" por "command": "python" e "args": ["-m", "bolsai_mcp"] no config JSON, desde que o pacote tenha sido instalado via pip install bolsai-mcp.

Erro: Python 3.10 required

O bolsai-mcp usa tipagem estrutural (match/case) e exige Python 3.10 ou superior. Em sistemas com Python 3.9 como padrão, uv resolve automaticamente baixando uma versão compatível. Em ambientes com pip, vale rodar python --version antes e usar pyenv ou uv python install 3.12 quando necessário.

Roadmap e limitações conhecidas

A cobertura atual do servidor contempla 350+ ações da B3, 400+ FIIs, 27 indicadores fundamentalistas e os principais indicadores macro do BCB. Fora do escopo: BDRs, opções, mercado de balcão, criptomoedas e ações listadas em bolsas internacionais. Essas lacunas são pela natureza do escopo do produto, não por limitação técnica do protocolo. Para cobertura de cripto ou mercados externos, servidores MCP especializados dessas classes podem ser rodados em paralelo no mesmo cliente.

Perguntas frequentes

O que é MCP (Model Context Protocol)?

MCP (Model Context Protocol) é um padrão aberto desenvolvido pela Anthropic em novembro de 2024 para conectar modelos de linguagem a fontes externas de dados e ferramentas. Um servidor MCP expõe funções que o LLM pode chamar durante uma conversa, recebendo respostas estruturadas em JSON. O protocolo desacopla a lógica de acesso a dados do modelo e padroniza a integração entre clientes (Claude Desktop, Claude Code, Cursor) e qualquer backend.

Preciso pagar para usar o bolsai-mcp?

Não. O plano gratuito da bolsai inclui 200 requisições por dia sem cartão de crédito e cobre todas as 10 ferramentas do bolsai-mcp, incluindo cotações, fundamentos, dividendos, FIIs e dados macro. O plano Pro (R$29/mês) amplia o limite para 10.000 requisições diárias e libera histórico completo de balanços. O custo de assinatura do Claude Desktop é separado e pertence à Anthropic.

Funciona com ChatGPT ou apenas Claude?

O bolsai-mcp, por ser um servidor MCP, funciona nativamente em clientes compatíveis com o protocolo: Claude Desktop, Claude Code, Cursor, Cline e Zed. Para ChatGPT, a integração é feita via GPT Actions (OpenAPI) em GPTs personalizados, que requerem assinatura ChatGPT Plus. As duas formas consomem os mesmos endpoints da API bolsai. A página /mcp traz as instruções de configuração para cada cliente.

Como obter uma API key da bolsai?

O cadastro é feito em usebolsai.com com login Google. Após criar a conta, a chave de API aparece no dashboard pronta para ser copiada. A mesma chave autentica requisições HTTP diretas para api.usebolsai.com e o servidor bolsai-mcp, bastando defini-la na variável de ambiente BOLSAI_API_KEY.

Leia também

O conteúdo deste artigo tem caráter educacional e técnico. Os dados citados refletem valores públicos disponíveis no momento da publicação e podem mudar. Nada aqui constitui recomendação de compra ou venda de ativos financeiros. Nomes de produtos e marcas pertencem aos respectivos titulares; Claude e Model Context Protocol são marcas da Anthropic PBC.