Como usar dados da B3 no Cursor com MCP (2026)

Por que conectar dados da B3 diretamente ao Cursor

O Cursor é um editor de código com um agente de IA integrado. Ele já escreve funções, refatora arquivos e roda comandos no terminal. A limitação aparece quando o pedido depende de dados externos que o modelo não conhece: "escreva um script que baixe os fundamentos da PETR4 e calcule o desconto frente ao setor". Sem uma fonte conectada, o agente monta uma URL imaginária, adota um esquema de resposta inventado e o programador só descobre o erro ao rodar.

O Model Context Protocol muda essa dinâmica. O MCP é um padrão aberto publicado 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 tipadas que o cliente (aqui, o Cursor) pode chamar durante a sessão, recebendo respostas estruturadas em JSON. A especificação está em modelcontextprotocol.io. O Cursor adotou o protocolo ao longo de 2025 e hoje qualquer servidor MCP fica disponível para o agente do editor.

Para o mercado brasileiro, isso significa que o agente do Cursor pode consultar cotações de fechamento, fundamentos calculados a partir da CVM, dividendos e dados macro do Banco Central sem sair do editor. O servidor bolsai-mcp faz essa ponte, expondo 10 ferramentas que cobrem 350+ ações, 400+ FIIs e 27+ indicadores fundamentalistas. O valor para quem desenvolve é direto: o código que o Cursor produz nasce ancorado na estrutura verdadeira da resposta.

Pré-requisitos

A configuração exige três itens. Nenhum deles é pago no ponto de partida.

• Cursor instalado em qualquer sistema operacional. O suporte a MCP está estável nas versões atuais do editor.
• uv (opcional, recomendado): o gerenciador de pacotes Python da Astral fornece o comando uvx, que executa o bolsai-mcp em ambiente isolado sem instalação global. A instalação está em docs.astral.sh/uv. O requisito de runtime é Python 3.10 ou superior.
• Uma API key da bolsai, gerada no dashboard com login Google. O plano gratuito libera 200 requisições por dia sem cartão, suficiente para configurar e testar o fluxo de análise.

Onde o Cursor guarda a configuração de MCP

O Cursor lê servidores MCP a partir de um arquivo chamado mcp.json, no mesmo formato JSON usado pelo claude_desktop_config.json do Claude Desktop. Existem dois escopos, e a distinção importa na hora de versionar o projeto:

• Global: ~/.cursor/mcp.json (no Windows, %USERPROFILE%\.cursor\mcp.json). O servidor fica disponível em todos os projetos abertos no Cursor.
• Por projeto: .cursor/mcp.json na raiz do repositório. O servidor vale apenas naquele workspace, e a configuração acompanha o repositório se for versionada.

Quando o mesmo servidor aparece nos dois arquivos, o de projeto prevalece sobre o global. Além dos arquivos, o Cursor também expõe a configuração pela interface, em Cursor Settings, na seção de ferramentas e MCP (rotulada como Tools & MCP nas versões recentes). A interface do editor muda de layout com frequência entre releases, então a referência autoritativa para o nome exato do menu e o formato aceito é a documentação oficial do Cursor em cursor.com/docs/mcp. O conteúdo do JSON, esse sim, permanece estável.

Configurando o bolsai-mcp no Cursor

A forma mais previsível de configurar é editar o arquivo mcp.json diretamente. Para deixar a análise da B3 disponível em qualquer projeto, use o arquivo global ~/.cursor/mcp.json. O conteúdo declara um objeto mcpServers com uma entrada nomeada bolsai:

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "bolsai": {
      "command": "uvx",
      "args": ["bolsai-mcp"],
      "env": {
        "BOLSAI_API_KEY": "sk_sua_chave_aqui"
      }
    }
  }
}

Os três campos são os mesmos de qualquer servidor stdio no Cursor: command aponta o executável (uvx), args passa os argumentos (bolsai-mcp) e env injeta variáveis de ambiente no processo do servidor. É exatamente a configuração usada no Claude Desktop, o que permite copiar a entrada entre os dois clientes sem alterar nada. Quem já leu o guia do MCP Server para B3 no Claude vai reconhecer o formato idêntico.

Mantendo a chave fora do arquivo versionado

Colocar a chave literal no mcp.json funciona, mas vaza o segredo se o arquivo for commitado. O Cursor resolve variáveis de configuração com a sintaxe ${env:NOME}, que lê a variável do ambiente do sistema no momento em que o processo é iniciado. A versão segura fica assim:

// .cursor/mcp.json (versionável, sem segredo embutido)
{
  "mcpServers": {
    "bolsai": {
      "command": "uvx",
      "args": ["bolsai-mcp"],
      "env": {
        "BOLSAI_API_KEY": "${env:BOLSAI_API_KEY}"
      }
    }
  }
}

Com essa forma, a chave real vive no ambiente (por exemplo, um export BOLSAI_API_KEY=sk_... no shell ou um gerenciador de segredos) e o arquivo pode ir para o repositório do time. Um detalhe importante: o Cursor lê os valores de env no momento em que o servidor sobe. Se a variável foi definida depois de o editor já estar aberto, é preciso reiniciar o Cursor para que a mudança seja lida.

Verificando a conexão

Depois de salvar o arquivo e reiniciar o editor, o servidor deve aparecer como ativo na seção Tools & MCP das configurações, com as ferramentas listadas. Se algo falhar, o MCP costuma falhar em silêncio, então o caminho de diagnóstico é ler os logs: no Cursor, o painel de saída (Output) tem uma entrada de MCP Logs que mostra a inicialização do servidor, as chamadas de ferramenta e mensagens de erro. Os problemas mais comuns são três: o uv não está no PATH, o pacote não foi encontrado ou a variável de ambiente está vazia.

O teste mais rápido é copiar o comando do mcp.json e rodá-lo direto no terminal. Se uvx bolsai-mcp subir sem erro com a variável exportada, o Cursor conseguirá subir também. Vale lembrar que o Cursor tem um teto em torno de 40 ferramentas ativas somando todos os servidores MCP; como o bolsai-mcp expõe 10, sobra folga confortável mesmo com outros servidores registrados.

As 10 ferramentas que o Cursor passa a enxergar

Uma vez conectado, o agente do Cursor ganha acesso a dez ferramentas do bolsai-mcp. Cada uma mapeia para um ou mais endpoints da API bolsai. O agente decide sozinho quais chamar e em que ordem, a partir do que você pede em linguagem natural.

A lista completa de ferramentas e seus parâmetros está documentada em /mcp. Vale notar que get_macro_indicator cobre selic, selic_target, ipca, cdi, usd_brl e eur_brl. Séries adicionais como IGP-M e Ibovespa existem na API REST, mas ficam fora do escopo da ferramenta MCP de macro.

Fluxo 1: a IA escreve um script de análise fundamentalista

O primeiro fluxo mostra o ganho central: a IA escreve código correto porque consultou a API antes de programar. No chat do Cursor, com o agente ativo, o pedido é direto:

# Prompt no chat do Cursor
Escreva um script Python que busca os fundamentos da PETR4
na API bolsai e imprime P/L, P/VP e ROE. Antes de escrever,
consulte a ferramenta get_fundamentals para confirmar os
nomes exatos dos campos na resposta.

O agente chama get_fundamentals("PETR4"), recebe o JSON e observa a estrutura real. Em vez de assumir que o campo de preço sobre lucro se chama price_earnings ou pe_ratio (chutes plausíveis), ele lê o nome verdadeiro: pl. A partir daí, gera um script que usa os campos corretos e a URL base correta:

# fundamentos_petr4.py (gerado pelo Cursor)
import requests

BASE = "https://api.usebolsai.com/api/v1"
API_KEY = "sk_sua_chave_aqui"

r = requests.get(
    f"{BASE}/fundamentals/PETR4",
    params={"api_key": API_KEY},
    timeout=10,
)
r.raise_for_status()
d = r.json()

print(f"{d['corporate_name']}")
print(f"P/L:  {d['pl']}")
print(f"P/VP: {d['pvp']}")
print(f"ROE:  {d['roe']}%")

O script roda de primeira porque cada nome de campo (corporate_name, pl, pvp, roe) veio da resposta observada, não de um palpite. O formato de saída fica assim, com os valores substituídos pelos números reais retornados no dia da consulta:

Os números concretos dependem do balanço mais recente ingerido: os fundamentos são recalculados após cada ingestão de demonstrações e o campo reference_date na resposta indica a data. A metodologia por trás de cada indicador (uso da conta CVM 3.11 para o lucro TTM, EBIT limpo, tratamento de bancos com as contas 2.07/2.08) está descrita em /docs.

Fluxo 2: screener de ações com um exemplo REST verificável

O segundo fluxo é o screening. Você descreve o critério em português e o agente do Cursor traduz para uma chamada ao endpoint /screener, que aceita operadores como _gt (maior que) e _lt (menor que) sobre qualquer campo de fundamentos. O prompt típico:

# Prompt no chat do Cursor
Escreva um script que use o endpoint /screener da bolsai
para listar ações com dividend yield acima de 6% e ROE
acima de 10%, ordenadas por dividend yield decrescente,
limitando a 10 resultados. Imprima ticker, P/L, ROE e DY.

O agente monta o script abaixo. Este é o exemplo executável do post: a requisição bate no endpoint /screener, que existe e responde com um objeto contendo a chave data, uma lista de empresas que atendem aos filtros.

# screener_dividendos.py
import requests

BASE = "https://api.usebolsai.com/api/v1"
API_KEY = "sk_sua_chave_aqui"

params = {
    "dividend_yield_gt": 6,
    "roe_gt": 10,
    "sort": "dividend_yield",
    "order": "desc",
    "limit": 10,
    "api_key": API_KEY,
}

r = requests.get(f"{BASE}/screener", params=params, timeout=15)
r.raise_for_status()

for a in r.json()["data"]:
    print(
        f"{a['ticker']:6} "
        f"P/L={a['pl']:6} "
        f"ROE={a['roe']:6}% "
        f"DY={a['dividend_yield']:5}%"
    )

A resposta do /screener traz, para cada empresa, campos como ticker, corporate_name, pl, pvp, roe, market_cap e dividend_yield. Um ponto que economiza depuração: dividend_yield aparece consolidado na resposta do screener, mas não existe dentro de /fundamentals/{ticker}. Para o yield de um ticker isolado fora do screener, a fonte é o endpoint /dividends/{ticker}. O agente do Cursor, ao consultar a ferramenta antes de escrever, percebe essa diferença e evita o erro clássico de ler dividend_yield de onde ele não está.

A saída tem o formato abaixo. Os tickers e números dependem dos dados de fechamento vigentes, então o bloco é ilustrativo do formato, não uma foto de valores atuais:

A partir daqui, expandir é conversa: "adicione um filtro de P/L abaixo de 15" vira pl_lt=15 na mesma chamada; "ordene por ROE" troca o sort. Como o agente conhece a resposta real, cada iteração continua produzindo código que roda. Para aprofundar a construção de screeners, o endpoint e seus filtros estão detalhados em /docs.

Fluxo 3: histórico de preços para análise e backtest

O terceiro fluxo puxa séries históricas de preço. O endpoint /stocks/{ticker}/history devolve OHLCV com colunas ajustadas por eventos corporativos, o que é indispensável para qualquer cálculo de retorno consistente. Um pedido comum no Cursor:

# Prompt no chat do Cursor
Baixe o histórico diário de VALE3 de 2023-01-01 até
2024-12-31 pela API bolsai, carregue em um DataFrame
pandas e calcule o retorno total no período usando o
preço de fechamento ajustado.

O agente gera um script que consome o endpoint de histórico, monta o DataFrame e calcula o retorno. Por consultar a ferramenta antes, ele usa o nome de coluna ajustado correto em vez de assumir um genérico como adj_close:

# historico_vale3.py (gerado pelo Cursor)
import requests
import pandas as pd

BASE = "https://api.usebolsai.com/api/v1"
API_KEY = "sk_sua_chave_aqui"

params = {
    "start": "2023-01-01",
    "end": "2024-12-31",
    "api_key": API_KEY,
}
r = requests.get(
    f"{BASE}/stocks/VALE3/history", params=params, timeout=30
)
r.raise_for_status()

df = pd.DataFrame(r.json()["data"])
df = df.sort_values("trade_date")

inicio = df["adjusted_close"].iloc[0]
fim = df["adjusted_close"].iloc[-1]
retorno = (fim / inicio - 1) * 100

print(f"Pregões: {len(df)}")
print(f"Retorno ajustado: {retorno:.1f}%")

O uso de adjusted_close em vez do fechamento bruto é o detalhe que separa um backtest correto de um enviesado: sem ajuste, um desdobramento ou uma reversão de ações produz saltos artificiais na série. O histórico de preços da bolsai vai de 1986 até o presente e aceita exportação em CSV com o parâmetro format=csv, útil para pipelines de dados. Quem quer se aprofundar em séries longas e ajuste por proventos encontra mais contexto no manual das ferramentas MCP.

Por que o código gerado com MCP quebra menos

O padrão dos três fluxos é o mesmo. Sem MCP, o agente do Cursor opera às cegas quanto à API: ele completa a partir de convenções vistas em treino, o que gera nomes como get_stock, fundamentals.pe ou close_adjusted. Alguns coincidem, muitos não, e cada divergência é um KeyError ou um 404 na execução.

Com o bolsai-mcp registrado, o ciclo muda: o agente chama a ferramenta, recebe o JSON verdadeiro, inspeciona os nomes de campo e só então escreve o código. A diferença não é de estilo, é de taxa de acerto. O modelo continua fazendo o que faz de melhor (estruturar a lógica, tratar erros, montar o DataFrame), mas para de adivinhar a parte que ele não teria como saber. Para um comparativo de como a bolsai se posiciona frente a outras APIs da B3 nesse quesito de profundidade de dados, o post bolsai vs brapi detalha as diferenças de cobertura.

Vale registrar o limite honesto: os dados são de fechamento. Preços e macro são atualizados diariamente às 20:30 (horário de Brasília), após o pregão; empresas, demonstrações, dividendos e FIIs, semanalmente. A bolsai não é corretora, não executa ordens e não fornece cotação intradiária. Para estratégias que dependem de dados em tempo real, o MCP resolve o acesso estruturado, mas a fonte permanece end-of-day.

Cursor, Claude Code ou um agente próprio?

O mesmo servidor bolsai-mcp funciona em qualquer cliente compatível com o protocolo. A escolha depende do fluxo de trabalho, não da capacidade de dados, que é idêntica.

• Cursor brilha quando o objetivo é produzir e rodar código: o agente escreve o script, executa no terminal integrado e itera no mesmo lugar. É o cenário deste guia.
• Claude Desktop e Claude Code servem melhor à análise conversacional e à exploração de dados sem necessariamente materializar um arquivo de código. O guia do MCP no Claude cobre esse caminho.
• Um agente próprio, construído com um framework de IA, consome o mesmo servidor MCP de forma programática. O post como construir um agente de IA para ações brasileiras mostra esse cenário de ponta a ponta.

Como o formato do mcp.json é compartilhado, migrar a configuração entre Cursor e Claude Desktop é literalmente copiar a entrada bolsai de um arquivo para o outro. A mesma chave em BOLSAI_API_KEY autentica todos.

Perguntas frequentes

Onde fica a configuração de MCP no Cursor?

O Cursor lê servidores MCP de um arquivo mcp.json. Há dois escopos: o global, em ~/.cursor/mcp.json (válido para todos os projetos), e o de projeto, em .cursor/mcp.json na raiz do repositório (vale só naquele workspace). Quando o mesmo servidor aparece nos dois arquivos, o de projeto prevalece. Também é possível adicionar pela interface, em Cursor Settings, na seção Tools & MCP. Como o Cursor muda o layout do menu com frequência, a documentação oficial em cursor.com/docs/mcp é a referência autoritativa.

O formato do mcp.json do Cursor é igual ao do Claude Desktop?

Sim. O Cursor usa o mesmo formato JSON do claude_desktop_config.json: um objeto mcpServers com uma chave por servidor, cada uma declarando command, args e env. Para o bolsai-mcp, a configuração é a mesma dos dois clientes: command uvx, args com bolsai-mcp e a variável BOLSAI_API_KEY em env. Isso permite copiar a configuração de um cliente para o outro sem alterações.

Por que deixar a IA chamar a API em vez de escrever o código sozinha?

Sem acesso a dados, um modelo de linguagem inventa nomes de endpoints, campos e formatos de resposta com base em padrões plausíveis, e o código gerado quebra em runtime. Com o servidor MCP ativo, o Cursor chama as ferramentas do bolsai-mcp durante a conversa, observa a estrutura real do JSON retornado e escreve o código Python usando os nomes de campo corretos. O resultado é código que roda de primeira porque foi construído sobre a resposta verdadeira da API, não sobre uma suposição.

Preciso de plano pago para usar o bolsai-mcp no Cursor?

Não. O plano gratuito da bolsai inclui 200 requisições por dia sem cartão de crédito e cobre as 10 ferramentas do bolsai-mcp: cotações, fundamentos, comparação, dividendos, busca de empresas, setores, histórico de preços, FIIs, macro e demonstrações financeiras. O plano Pro (R$49/mês) amplia o limite para 10.000 requisições diárias e libera histórico completo. A chave sai do dashboard em usebolsai.com/dashboard.

Os dados da B3 no Cursor são em tempo real?

Não. Os dados da bolsai são de fechamento (end-of-day). Preços e indicadores macro são atualizados diariamente às 20:30 (horário de Brasília), após o fechamento do pregão da B3. Empresas, demonstrações financeiras, dividendos e FIIs são atualizados semanalmente. A cobertura é da bolsa brasileira; a bolsai não é corretora, não executa ordens e não oferece cotação intradiária.

Leia também

O conteúdo deste artigo tem caráter educacional e técnico, com data de referência 2 de julho de 2026. Os dados citados refletem valores públicos disponíveis no momento da consulta à API e podem mudar. Nada aqui constitui recomendação de compra ou venda de ativos financeiros. Nomes de produtos e marcas pertencem aos respectivos titulares; Cursor é marca da Anysphere, e Claude e Model Context Protocol são marcas da Anthropic PBC.