Agente de Análise de Ações da B3 no Terminal com Claude Code: MCP, Screener e Fundamentos (2026)

Claude Code + MCP no terminal: o que muda em relação ao Claude Desktop

O Claude Code é o cliente de linha de comando da Anthropic. Diferente do Claude Desktop, que é um aplicativo gráfico e lê servidores de um arquivo claude_desktop_config.json, o Claude Code gerencia servidores MCP pela própria CLI: você adiciona, lista, inspeciona e remove servidores com subcomandos claude mcp. Para quem já vive no shell, isso elimina a etapa de editar JSON à mão e reiniciar um app: um comando registra o servidor e a sessão seguinte já enxerga as ferramentas.

A vantagem prática para análise de ações é o encadeamento. No terminal, o resultado de um agente de dados da B3 via MCP pode virar entrada de um script, alimentar um pipe, ou ficar registrado no histórico do shell. O modelo decide quais ferramentas chamar e em que ordem, mas o ambiente ao redor é o mesmo onde o desenvolvedor já roda git, python e jq. É o cenário natural para transformar research fundamentalista em rotina reproduzível.

Pré-requisitos

São três dependências, todas de instalação rápida:

• Claude Code: o CLI da Anthropic instalado e autenticado. A referência oficial de MCP está em code.claude.com/docs/en/mcp.
• uv / uvx: o gerenciador de pacotes Python da Astral. O uvx executa o bolsai-mcp em um ambiente isolado, sem instalação global. Guia em docs.astral.sh/uv. O requisito mínimo é Python 3.10.
• API key da bolsai: a chave que autentica o servidor. Sai do dashboard após o cadastro com login Google, no header X-API-Key. O plano gratuito dá 200 requisições por dia, sem cartão.

Se preferir instalar o uv antes de tudo, o comando em sistemas Unix é curl -LsSf https://astral.sh/uv/install.sh | sh. No Windows, siga o instalador oficial. Com o uvx disponível no PATH, o Claude Code consegue subir o servidor sob demanda.

Adicionando o bolsai-mcp com claude mcp add

O comando claude mcp add (stdio)

O bolsai-mcp é um servidor stdio: roda como processo local e conversa com o Claude Code por entrada e saída padrão. A sintaxe geral do Claude Code para servidores stdio é claude mcp add [opções] <nome> -- <comando> [args]. O comando abaixo é o que você roda na prática:

# Registrar o bolsai-mcp no Claude Code (servidor stdio local)
claude mcp add bolsai -e BOLSAI_API_KEY=sk_sua_chave -- uvx bolsai-mcp

Dois detalhes importam na ordem dos argumentos. O -e BOLSAI_API_KEY=... injeta a variável de ambiente no processo do servidor e precisa vir depois do nome (bolsai), nunca antes: a flag é variádica e, colada ao começo, engoliria o nome do servidor como se fosse mais um par. O -- (dois traços) separa as opções do Claude Code do comando que efetivamente sobe o servidor. Tudo que vem depois do -- (aqui, uvx bolsai-mcp) é passado adiante sem o Claude Code tentar interpretar como flag própria.

Por padrão o servidor é adicionado no escopo local (visível só para você, no projeto atual). Para deixá-lo disponível em qualquer diretório da sua máquina, acrescente --scope user antes do --. Feito o registro, confirme que o Claude Code enxerga o servidor:

# Listar servidores registrados
claude mcp list

# Saída esperada (resumida)
bolsai: uvx bolsai-mcp - ✓ Connected

# Detalhes de um servidor específico
claude mcp get bolsai

Dentro de uma sessão do Claude Code, o comando /mcp abre o painel de status: mostra cada servidor conectado e a contagem de ferramentas expostas. Ao rodar /mcp com o bolsai ativo, aparecem as 11 ferramentas do servidor, prontas para o modelo chamar durante a conversa.

Config JSON equivalente

O claude mcp add grava a configuração em um arquivo JSON. O bloco resultante é equivalente ao que se coloca no claude_desktop_config.json do aplicativo gráfico, com a mesma tríade command / args / env:

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

Quem quiser entender o mesmo servidor pelo caminho gráfico pode conferir o guia do bolsai-mcp com Claude Desktop, que detalha os caminhos do arquivo por sistema operacional. Em editores com IA, a mesma entrada vale no Windsurf (chave mcpServers) e no VS Code com o GitHub Copilot (chave servers, só em agent mode). A documentação do bolsai-mcp traz as variações para cada cliente MCP.

Fluxo de agente no terminal

Com o servidor conectado, o padrão mais produtivo é encadear três etapas em uma mesma sessão: filtrar o universo, aprofundar os candidatos e comparar os finalistas. O Claude Code decide sozinho quais das 11 ferramentas chamar e em que ordem. As saídas abaixo são ilustrativas do formato retornado.

Screening: "ações com DY > 8% e P/VP < 1"

O ponto de partida do agente é reduzir centenas de tickers a uma lista curta. Um pedido em linguagem natural vira uma chamada à ferramenta screen_stocks, que aceita filtros por indicador.

# Prompt no Claude Code
Liste ações da B3 com dividend yield acima de 8% e
P/VP abaixo de 1. Ordene pelo maior DY.

# Claude Code chama:
# screen_stocks({
#   "dividend_yield_gt": 8, "pvp_lt": 1,
#   "sort": "dividend_yield_desc", "limit": 10 })

# Resultado (resumido) no terminal:
Ticker    DY 12m    P/VP    P/L     Setor
BBAS3     9.8%      0.82    4.6     Bancos
CMIG4     9.1%      0.94    5.1     Utilities
CXSE3     8.9%      0.88    7.2     Seguros
GGBR4     8.6%      0.71    6.0     Siderurgia
CPLE6     8.3%      0.79    5.9     Utilities

Refinamentos entram no mesmo turno. "Tire os bancos e mantenha só quem tem dívida líquida sobre EBITDA abaixo de 2x" resulta em nova chamada ao screen_stocks com filtros adicionais. O conjunto completo de parâmetros aceitos está em /docs. A mesma lógica de filtragem, feita em Python puro, aparece no guia de como construir um screener de ações em Python.

Aprofundar: get_fundamentals + get_dividends

Com a lista curta, o agente desce ao nível do ativo. Para cada candidato relevante, chama get_fundamentals (os 27 indicadores calculados com TTM) e get_dividends (histórico e DY dos últimos 12 meses).

# Prompt no Claude Code
Detalhe BBAS3 e CMIG4: ROE, margem líquida, dívida
líquida/EBITDA e consistência dos dividendos.

# Claude Code chama get_fundamentals e get_dividends
# para cada ticker. Trecho de get_fundamentals("BBAS3"):
{
  "ticker": "BBAS3",
  "pl": 4.6,
  "pvp": 0.82,
  "roe": 21.3,
  "net_margin": 28.7,
  "reference_date": "2026-03-31"
}

# Síntese do Claude Code:
BBAS3 combina ROE de 21.3% com P/VP de 0.82, sinal
clássico de banco descontado. O DY de 9.8% vem de um
payout estável nos últimos 4 anos. CMIG4 entrega DY
parecido, porém com fluxo mais sensível ao ciclo tarifário.

Comparar: compare_stocks + get_price_history

A etapa final coloca os finalistas lado a lado. A ferramenta compare_stocks aceita uma lista de tickers e devolve os fundamentos em paralelo; get_price_history traz a série de preços ajustada por proventos para contextualizar o momento de entrada.

# Prompt no Claude Code
Compare BBAS3, CMIG4 e GGBR4 e me diga qual está mais
descontada frente ao próprio histórico de 5 anos.

# Claude Code chama:
# 1. compare_stocks({"tickers": ["BBAS3","CMIG4","GGBR4"]})
# 2. get_price_history(...) para cada ticker (5 anos)

# Resposta do Claude Code:
Nos três, o P/VP atual está abaixo da mediana de 5 anos.
BBAS3 é o caso mais nítido: negocia a 0.82 contra mediana
histórica de ~1.05. GGBR4, cíclica, exige cautela: o P/L
baixo reflete lucro de pico de ciclo, não desconto estrutural.
Para renda, BBAS3 tem o perfil mais defensável do trio.

O ganho do fluxo no terminal é a rastreabilidade: cada número da síntese final veio de uma tool call registrada na sessão. Nada foi inventado pelo modelo nem copiado de uma página que pode ter mudado. Para montar um agente autônomo em Python, com loop de tool use fora do REPL, vale ver o agente de análise de ações com Claude e MCP.

Dados oficiais calculados vs repositórios de scraping

A alternativa comum a uma API de dados é clonar um scraper de GitHub que raspa Fundamentus ou Status Invest. Funciona em uma tarde de fim de semana e falha em produção. A diferença aparece exatamente no ponto em que o agente precisa confiar no número.

O problema mais insidioso do scraper é a falha silenciosa. Quando o Fundamentus muda uma classe de CSS ou reordena uma tabela, o parser não estoura exceção: ele devolve o campo vizinho, um None convertido em zero, ou o valor de outra ação. O agente segue adiante com um número plausível e errado, e a análise inteira herda o defeito sem aviso. Uma API oficial com metodologia publicada troca esse risco por uma tool call auditável, que é o que sustenta um agente de research levado a sério. O detalhamento de como cada múltiplo é calculado está em /docs.

Troubleshooting

O servidor não persiste entre sessões

Se claude mcp list não mostra o bolsai em um novo diretório, o servidor provavelmente foi adicionado no escopo local (o padrão), que é atrelado ao projeto atual. Rode novamente com --scope user para registrá-lo globalmente: claude mcp add --scope user bolsai -e BOLSAI_API_KEY=sk_... -- uvx bolsai-mcp. Servidores de escopo project gravados em um .mcp.json versionado só ficam ativos depois que você confia no diretório ao abrir o Claude Code nele.

uvx: command not found

O Claude Code registra o servidor, mas a conexão falha porque o uvx não está no PATH. Instale o uv com curl -LsSf https://astral.sh/uv/install.sh | sh em Unix e reabra o terminal. Se preferir não depender do uvx, instale o pacote com pip install bolsai-mcp em um ambiente com Python 3.10+ e troque o comando de subida por python -m bolsai_mcp no lugar de uvx bolsai-mcp.

401 Unauthorized ou 429 Too Many Requests

O 401 quase sempre é a BOLSAI_API_KEY: chave com espaço invisível ao copiar, chave revogada no dashboard, ou variável passada errada no -e. Rode claude mcp get bolsai para conferir o env registrado. O 429 significa que a cota diária acabou: são 200 requisições por dia no plano gratuito, e uma sessão de agente com muitas tool calls encadeadas consome rápido. A saída é o plano Pro (R$49/mês, 10.000 requisições/dia) ou esperar a janela de 24h resetar.

Perguntas frequentes

Como adicionar um MCP server ao Claude Code?

Use o comando claude mcp add no terminal. Para um servidor stdio local, a sintaxe é claude mcp add <nome> -e VAR=valor -- <comando> <args>. Para o bolsai-mcp, rode claude mcp add bolsai -e BOLSAI_API_KEY=sk_sua_chave -- uvx bolsai-mcp. O -e passa variáveis de ambiente e deve vir depois do nome do servidor e antes do separador --, que isola as opções do Claude Code do comando que sobe o servidor. Confirme com claude mcp list e inspecione as ferramentas com /mcp dentro da sessão.

Dá para rodar um screener de ações da B3 no terminal?

Sim. Com o bolsai-mcp conectado ao Claude Code, um pedido como "ações com DY acima de 8% e P/VP abaixo de 1" é traduzido pelo modelo em uma chamada à ferramenta screen_stocks, que devolve a lista ordenada direto no terminal. A partir daí o mesmo agente aprofunda os candidatos com get_fundamentals e get_dividends e compara os finalistas com compare_stocks, sem trocar de janela nem abrir um dashboard.

Qual a diferença para scrapers do Fundamentus no GitHub?

Scrapers do Fundamentus ou Status Invest publicados no GitHub raspam HTML de páginas que mudam sem aviso, então quebram silenciosamente quando o layout muda e costumam não documentar metodologia nem ajustar histórico por proventos. O bolsai parte de fontes oficiais (CVM e B3), calcula os indicadores com metodologia documentada e publica benchmark aberto de 96% de concordância com o Fundamentus em dados frescos. No Claude Code, isso significa que cada número que entra na análise vem de uma tool call auditável, não de um parser frágil.

Preciso pagar para usar o bolsai-mcp no Claude Code?

Não. O plano gratuito da bolsai inclui 200 requisições por dia sem cartão de crédito e cobre todas as 11 ferramentas do bolsai-mcp. O plano Pro (R$49/mês) amplia o limite para 10.000 requisições diárias e libera histórico completo de balanços. A assinatura do Claude Code pertence à Anthropic e é cobrada à parte.

Leia também

Referências: Claude Code MCP (docs.anthropic.com), modelcontextprotocol.io e b3.com.br.

O conteúdo deste artigo tem caráter educacional e técnico. Os dados e valores citados são ilustrativos, refletem informações públicas 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, Claude Code e Model Context Protocol são marcas da Anthropic PBC.