Análise de FIIs no Claude Desktop com MCP (2026)

Por que analisar FIIs dentro do Claude Desktop

O fluxo tradicional de quem acompanha fundos imobiliários envolve abrir várias abas: um site para o P/VP, outro para o histórico de distribuições, um terceiro para a composição da carteira de imóveis. Cada consulta é manual, e cruzar os números entre fundos exige copiar e colar em uma planilha. O Model Context Protocol muda esse fluxo ao permitir que o próprio assistente de IA busque os dados durante a conversa.

O MCP é um padrão aberto publicado pela Anthropic em novembro de 2024 para conectar modelos de linguagem a fontes externas de dados. Um servidor MCP expõe ferramentas que o modelo pode invocar; o cliente (Claude Desktop, Claude Code, Cursor) faz a ponte. Quando o servidor é o bolsai-mcp, essas ferramentas trazem dados da bolsa brasileira — incluindo cobertura dedicada a fundos imobiliários. Se você quiser o panorama completo do protocolo e das ferramentas de ações, o post MCP Server para B3: como conectar Claude aos dados da bolsa cobre a instalação geral em detalhe.

Para FIIs, o ganho é específico. Fundos imobiliários se avaliam por um conjunto de métricas próprias — P/VP, dividend yield, vacância, valor patrimonial líquido, composição entre tijolo e papel — e a interpretação depende muito do segmento. Um dividend yield que parece alto num fundo de recebíveis pode ser normal, e o mesmo número num fundo de lajes corporativas pode sinalizar risco de vacância. Um assistente com acesso aos dados brutos consegue trazer o número certo e contextualizá-lo no mesmo turno.

O que os dados de FIIs da bolsai incluem

Antes de instalar qualquer coisa, vale entender o que está disponível. A bolsai cobre 400+ FIIs da B3, e os dados vêm de fontes oficiais: preços da B3 e informes periódicos entregues à CVM. Os campos que a ferramenta get_fii_details expõe cobrem quatro dimensões.

Valuation e rendimento

O pvp (preço sobre valor patrimonial) indica se o fundo negocia com ágio ou desconto frente ao patrimônio contábil. O dividend_yield_ttm mede o rendimento distribuído nos últimos doze meses, e o dy_month_pct traz o yield referente ao último mês. O net_asset_value é o valor patrimonial líquido (NAV), e o book_value_per_share é o valor patrimonial por cota — base do cálculo de P/VP.

Ocupação e carteira de imóveis

Para fundos de tijolo, os campos operacionais são decisivos: vacancy_pct (vacância), delinquency_pct (inadimplência), leased_pct (percentual alugado), property_count (número de imóveis), total_area_sqm (área total em metros quadrados) e top_properties (principais propriedades). O campo property_reference_date informa a data de referência desses dados operacionais.

Classificação e composição

O fund_type classifica o fundo em Tijolo, Papel, Fundo de Fundos ou Híbrido, e o segment detalha o segmento (logística, lajes, shoppings, recebíveis, papel, tijolo, híbrido). O mandate descreve o mandato de investimento do fundo. O bloco asset_composition abre a carteira em percentuais: imóveis alugados (real_estate_leased_pct), em construção (real_estate_under_construction_pct), à venda, terrenos, CRI (cri_pct), LCI, debêntures, cotas de outros FIIs (fii_holdings_pct), ações e caixa (cash_pct).

Gestão e cadastro

Complementam o cadastro os campos administrator e administrator_cnpj (administrador e CNPJ), inception_date (data de início), duration_type (prazo determinado ou indeterminado), target_investors (público-alvo), fees_paid_last_month (taxas pagas no último mês), além de website e email. Duas ferramentas auxiliares completam o quadro: distribuições históricas e concentração de inquilinos por setor. Para FIIs de tijolo, esse último ponto — a exposição a um único locatário — é um fator de risco relevante que os dados da CVM permitem quantificar.

Passo 1: obter a API key e instalar o bolsai-mcp

A chave de API sai do dashboard em usebolsai.com/dashboard após o cadastro com login Google. O plano gratuito dá 200 requisições por dia — o suficiente para várias sessões de research de FIIs. Guarde a chave; ela vai na configuração do Claude Desktop.

O servidor é o pacote Python bolsai-mcp. A forma mais limpa de rodá-lo é via uvx, o executor do gerenciador uv, que cria um ambiente isolado automaticamente. 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

Não é obrigatório rodar o comando manualmente — o Claude Desktop o inicia sozinho a partir da configuração. Mas executá-lo uma vez ajuda a confirmar que o uvx está no PATH antes de mexer no JSON. Quem prefere não instalar nada localmente encontra alternativas para Claude Code, Cursor e clientes remotos na página /mcp.

Passo 2: configurar o Claude Desktop

O Claude Desktop lê servidores MCP a partir do arquivo claude_desktop_config.json. A forma mais direta de abri-lo é pelo próprio app: no menu Claude (barra de menu do sistema, no macOS) abra Settings…, vá até a aba Developer na barra lateral e clique em Edit Config. Isso cria o arquivo se ele ainda não existir e o abre no editor padrão.

Se preferir localizar o arquivo manualmente, os caminhos por sistema operacional são:

• 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 declara o servidor bolsai. Cole exatamente esta estrutura, trocando sk_sua_chave_aqui pela chave copiada do dashboard:

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

Depois de salvar, feche e reabra o Claude Desktop por completo — no macOS, botão direito no ícone do dock e "Encerrar"; no Windows, botão direito no ícone da bandeja e "Sair". Recarregar a janela não basta; o servidor só é lido na inicialização. Quando o app volta, um ícone de ferramenta (o "martelo") aparece na área de mensagem: clique nele para ver as ferramentas do bolsai listadas. A primeira invocação de cada ferramenta pede consentimento explícito, comportamento padrão do protocolo.

Uma observação para o Windows: em algumas versões é preciso envolver o comando em cmd /c, ou seja, "command": "cmd" e "args": ["/c", "uvx", "bolsai-mcp"]. Nas versões recentes do Claude Desktop (2026) também existe um painel de Connectors e o suporte a extensões empacotadas (arquivos .mcpb), que instalam servidores MCP com duplo clique; a edição do JSON, porém, continua funcionando para qualquer servidor e dá controle total sobre variáveis de ambiente.

Passo 3: a primeira análise de FII por conversa

Com o servidor ativo, a validação mais rápida é pedir os fundamentos de um FII conhecido. O prompt abaixo dispara uma chamada à ferramenta get_fii_details, e o Claude resume os campos retornados. Os números a seguir são ilustrativos — servem para mostrar o formato da resposta, não valores atuais de mercado.

# Prompt do usuário
Claude, me dá um resumo do HGLG11: P/VP, dividend yield
dos últimos 12 meses, vacância e segmento.

# Claude chama: get_fii_details({"ticker": "HGLG11"})
# Resposta da ferramenta terá o formato (valores ilustrativos):
{
  "ticker": "HGLG11",
  "segment": "logistica",
  "fund_type": "Tijolo",
  "pvp": 0.9X,
  "dividend_yield_ttm": 8.X,
  "dy_month_pct": 0.7X,
  "vacancy_pct": X.X,
  "property_count": 2X,
  "net_asset_value": ...,
  "property_reference_date": "2026-0X-XX"
}

# Resposta textual do Claude (ilustrativa):
HGLG11 é um FII de logística (tijolo). Negocia a um P/VP
de ~0,9X, com dividend yield de ~8,X% nos últimos 12 meses
e vacância de X,X%. A carteira soma 2X imóveis. O desconto
frente ao valor patrimonial e a baixa vacância são pontos
a observar; o yield do mês (dy_month_pct) ajuda a ver se
a distribuição recente está acima ou abaixo da média anual.

Repare que o Claude não inventa os números: ele lê o JSON de get_fii_details e o descreve. Isso é o oposto de perguntar a um chatbot sem ferramentas, que responderia com dados desatualizados ou fabricados. Aqui, cada valor vem do endpoint /fiis/HGLG11, atualizado com preços de fim de dia (20:30 BRT) e informes da CVM.

Comparação de FIIs do mesmo segmento

O caso em que a análise conversacional mais rende é a comparação. Em vez de abrir três páginas, você descreve o pedido e o Claude chama get_fii_details uma vez por fundo, consolidando o resultado numa tabela. O exemplo abaixo compara três FIIs de logística — de novo, com valores ilustrativos.

# Prompt do usuário
Compare HGLG11, KNRI11 e XPML11: P/VP, dividend yield 12m,
vacância e número de imóveis. Qual está mais descontado?

# Claude chama get_fii_details para cada ticker.
# Consolidado (valores ilustrativos, não reais):
Ticker    Segmento     P/VP    DY 12m    Vacância   Imóveis
HGLG11    logistica    0,9X    8,X%      X,X%       2X
KNRI11    hibrido      0,9X    7,X%      X,X%       XX
XPML11    shoppings    1,0X    8,X%      X,X%       XX

# Análise textual do Claude (ilustrativa):
Os três atuam em segmentos diferentes, então a comparação
direta de yield exige cautela: shoppings e logística têm
dinâmicas de vacância distintas. Em termos de P/VP, o fundo
com múltiplo mais baixo negocia com o maior desconto sobre
o patrimônio — mas vale cruzar isso com a vacância, porque
desconto acompanhado de vacância alta pode refletir risco
de queda na distribuição, não uma oportunidade.

O valor está na síntese: o modelo traz os números da API e adiciona o raciocínio que separa desconto genuíno de armadilha de valor. Como os segmentos de FIIs têm perfis de risco diferentes, comparar apenas o yield engana. Se você quiser entender a fundo cada categoria — logística, lajes, shoppings, recebíveis — o post tipos de FIIs: logística, laje, shopping e recebíveis detalha o que esperar de cada segmento.

Screening de FIIs por conversa

Além de analisar fundos que você já conhece, dá para descobrir novos com o screener de FIIs. Em linguagem natural, um pedido como "FIIs de logística com P/VP abaixo de 1 e dividend yield acima de determinado patamar" é traduzido pelo Claude em filtros da ferramenta de screening, que roda sobre o endpoint /fiis/screener.

O screener aceita filtros numéricos com operadores _gt (maior que) e _lt (menor que) sobre campos como pvp, dividend_yield_ttm, dy_month_pct, close_price, net_asset_value, book_value_per_share, vacancy_pct, delinquency_pct, leased_pct, property_count, total_area_sqm, total_shareholders e shares_outstanding. E aceita filtros categóricos por segment, fund_type, mandate, management_type e administrator.

# Prompt do usuário
Liste FIIs do segmento de logística com P/VP abaixo de 1
e vacância abaixo de 5%. Ordene pelo dividend yield.

# O Claude traduz para o screener de FIIs, equivalente a:
# /fiis/screener?segment=logistica
#   &pvp_lt=1&vacancy_pct_lt=5
#   &sort=dividend_yield_ttm&order=desc

# A resposta traz uma lista de FIIs que atendem aos
# critérios, com pvp, dividend_yield_ttm e vacancy_pct
# de cada um — todos filtrados a partir dos dados reais
# de fim de dia. O Claude então comenta os padrões
# observados (ex.: quantos fundos cumprem os filtros,
# qual a faixa de P/VP do grupo resultante).

A grande vantagem é a reprodutibilidade: todos os critérios ficam registrados na conversa. Se depois você quiser apertar o filtro — "agora só os que têm mais de 15 imóveis" — o Claude acrescenta property_count_gt=15 à chamada e refaz a busca. Combinar segmento, valuation e ocupação num único pedido é exatamente o tipo de tarefa que um dashboard estático torna trabalhosa e que a conversa torna fluida.

Histórico de distribuições com get_dividends

Rendimento passado é parte central da tese de qualquer FII. A ferramenta get_dividends atende tanto ações quanto fundos imobiliários e detecta FIIs automaticamente pelo sufixo "11" do ticker — não é preciso indicar que se trata de um fundo. Ela retorna o histórico de distribuições por data ex e valor, permitindo ao Claude analisar a consistência e a tendência dos proventos.

# Prompt do usuário
Como foram as distribuições mensais do MXRF11 nos
últimos 3 anos? A distribuição está estável ou caindo?

# Claude chama: get_dividends({"ticker": "MXRF11", "years": 3})
# (FII detectado automaticamente pelo sufixo "11")

# A ferramenta retorna a lista de distribuições com data
# ex e valor por cota. O Claude então descreve a série:
# regularidade dos pagamentos mensais, meses atípicos
# e a tendência geral — sem afirmar valores como fato
# atual, apenas resumindo o que os dados mostram.

Combinar get_dividends com get_fii_details num mesmo diálogo é poderoso: o primeiro mostra a trajetória dos proventos, o segundo revela se essa distribuição é sustentada por imóveis alugados (baixa vacância) ou por uma carteira de recebíveis. Para explorar os endpoints REST que essas ferramentas consomem por baixo dos panos, o post API de fundos imobiliários em Python: dividendos e P/VP traz exemplos diretos em código.

Ferramentas de FIIs no bolsai-mcp: referência

Duas das dez ferramentas do bolsai-mcp são centrais para fundos imobiliários. As demais (cotações, macro, comparação) também aceitam tickers de FII quando fizer sentido. A tabela resume o que cada uma dedicada a FIIs entrega.

A ferramenta get_macro_indicator merece destaque no contexto de FIIs. Ela expõe séries como Selic, CDI e IPCA, o que permite ao Claude comparar o dividend yield de um fundo com o custo de oportunidade da renda fixa — uma conta que todo investidor de FII faz. Note que, via MCP, o get_macro_indicator cobre selic, selic_target, ipca, cdi, usd_brl e eur_brl.

# Prompt do usuário
Com a Selic atual, um FII de recebíveis com DY de 12%
paga prêmio suficiente sobre o CDI?

# Claude combina ferramentas:
# 1. get_macro_indicator({"indicator": "selic"})
# 2. get_macro_indicator({"indicator": "cdi"})

# O Claude compara o DY informado com o CDI corrente,
# lembra que FIIs de papel têm risco de crédito e
# marcação a mercado, e que a isenção de IR sobre os
# rendimentos de FIIs (para pessoa física, nas regras
# vigentes) altera a comparação líquida com o CDI.

Prefere código? O mesmo dado via REST

O MCP é conveniente para research conversacional, mas por baixo tudo é a API REST da bolsai. Se você quer automatizar ou integrar num pipeline, o exemplo abaixo consulta os detalhes de um FII com Python e requests. Não existe SDK oficial; a biblioteca requests basta.

import requests

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

# Detalhes de um FII
r = requests.get(
    f"{BASE}/fiis/HGLG11",
    params={"api_key": "sua_chave"},
)
fii = r.json()
print(fii["segment"], fii["fund_type"])
print("P/VP:", fii["pvp"])
print("DY 12m:", fii["dividend_yield_ttm"])
print("Vacância:", fii["vacancy_pct"])

# Screener: logística, P/VP < 1, ordenado por DY
s = requests.get(
    f"{BASE}/fiis/screener",
    params={
        "api_key": "sua_chave",
        "segment": "logistica",
        "pvp_lt": 1,
        "sort": "dividend_yield_ttm",
        "order": "desc",
        "limit": 20,
    },
)
for fund in s.json():
    print(fund["ticker"], fund["pvp"], fund["dividend_yield_ttm"])

Os mesmos campos aparecem no MCP e no REST, porque a ferramenta get_fii_details é apenas um invólucro sobre /fiis/{ticker}. A documentação completa dos parâmetros e campos está em /docs. Vale lembrar que qualquer endpoint de lista aceita ?format=csv, o que permite puxar um screening de FIIs direto para o Google Sheets com =IMPORTDATA(...).

Limitações e boas práticas

Três pontos ajudam a usar a análise de FIIs com IA de forma correta e sem frustração.

Dados são de fim de dia, não intradiários

Preços e cotações de FIIs são atualizados uma vez por dia, às 20:30 (horário de Brasília), após o fechamento da B3. Dados cadastrais, composição de ativos e distribuições são atualizados semanalmente. A bolsai não é uma corretora e não oferece cotação em tempo real nem execução de ordens. Para análise fundamentalista e comparação de fundos, o dado de fim de dia é o padrão adequado; para day trade, não é a ferramenta certa.

Peça o dado, não a opinião

O modelo é bom em recuperar e organizar números via ferramentas, mas nada aqui é recomendação de investimento. Prompts que pedem "quais os melhores FIIs para comprar agora" geram respostas genéricas; prompts que pedem "compare a vacância e o P/VP destes fundos e me diga qual tem maior desconto sobre o patrimônio" geram análises úteis e verificáveis, porque se apoiam em campos concretos como vacancy_pct e pvp.

Erros comuns de configuração

Se as ferramentas não aparecem no ícone de martelo, o problema costuma ser: sintaxe do JSON inválida (uma vírgula a mais desativa silenciosamente todos os servidores), o Claude Desktop não foi reiniciado por completo, ou o uvx não está no PATH. Um erro 401 nos logs indica chave inválida — normalmente um espaço invisível copiado junto. Um erro 429 indica que as 200 requisições diárias do plano gratuito acabaram; o plano Pro (R$49/mês) sobe o limite para 10.000 por dia. No macOS, os logs ficam em ~/Library/Logs/Claude.

Perguntas frequentes

Como analisar FIIs com IA no Claude Desktop?

Instale o pacote bolsai-mcp e adicione-o ao arquivo claude_desktop_config.json com sua BOLSAI_API_KEY. Depois de reiniciar o Claude Desktop, peça análises de fundos imobiliários em linguagem natural. O modelo aciona get_fii_details (P/VP, dividend yield, NAV, vacância, composição de ativos), get_dividends (distribuições, que detecta FIIs pelo sufixo "11") e o screener de FIIs, retornando dados oficiais de fim de dia processados a partir de B3 e CVM.

Quais dados de FIIs o bolsai-mcp fornece?

A ferramenta get_fii_details retorna P/VP, dividend yield (TTM e do mês), NAV (net_asset_value), vacância, inadimplência, percentual alugado, tipo de fundo (Tijolo, Papel, Fundo de Fundos, Híbrido), mandato, segmento, número de imóveis, área total, composição de ativos (imóveis, CRI, LCI, debêntures, caixa) e principais propriedades. A ferramenta get_dividends devolve o histórico de distribuições por data ex e valor.

Os dados de FIIs são em tempo real?

Não. Os preços de FIIs são de fim de dia, atualizados diariamente às 20:30 (horário de Brasília), após o fechamento da B3. Dados cadastrais, composição e distribuições são atualizados semanalmente. A bolsai não oferece cotação intradiária nem execução de ordens, e o conteúdo tem caráter informativo, não constituindo recomendação de investimento.

Preciso pagar para analisar FIIs com o bolsai-mcp?

Não. O plano gratuito da bolsai inclui 200 requisições por dia sem cartão de crédito e cobre as ferramentas de FIIs. O plano Pro (R$49/mês) amplia o limite para 10.000 requisições diárias e libera o histórico completo. A assinatura do Claude Desktop é separada e pertence à Anthropic. Você cria sua conta e obtém a chave em usebolsai.com/dashboard.

Leia também

O conteúdo deste artigo tem caráter educacional e técnico. Os exemplos de resposta são ilustrativos e usam números hipotéticos; valores reais mudam a cada atualização e devem ser consultados diretamente pela API. 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.