FinBrain MCP

Acesse dados financeiros alternativos de nível institucional diretamente em seus fluxos de trabalho de LLM.

GitHub
9
Experimente este MCPPatrocinado

Documentação

FinBrain MCP 

PyPI version CI License

Requer Python 3.10+

Um servidor Model Context Protocol (MCP) que expõe os conjuntos de dados da FinBrain para clientes de IA (Claude Desktop, extensões MCP do VS Code, etc.) por meio de ferramentas simples. Baseado no SDK oficial finbrain-python (API v2).

Recursos

Previsões de preços com IA

Acesse as previsões de preços por machine learning da FinBrain com horizontes diário (10 dias) e mensal (12 meses). Inclui previsões médias com intervalos de confiança de 95%.

Análise de notícias e sentimento

Navegue por artigos de notícias recentes de qualquer ticker ou acompanhe pontuações agregadas de sentimento diário ao longo do tempo. Faça uma triagem de notícias em todas as ações monitoradas.

Dados alternativos

  • Métricas do LinkedIn — Contagem de funcionários e tendências de seguidores como indicadores de saúde da empresa
  • Avaliações da App Store — Dados de desempenho de aplicativos móveis para empresas voltadas ao consumidor
  • Fluxo de opções — Índices de put/call e volume para avaliar o posicionamento do mercado
  • Menções no Reddit — Contagens de menções de tickers em subreddits, coletadas a cada 4 horas
  • Contratos governamentais — Contratos governamentais dos EUA do USAspending.gov
  • Registros de patentes — Patentes concedidas pelo USPTO mapeadas para tickers por cessionário corporativo, com classificação CPC

Atividade institucional e de insiders

  • Negociações do Congresso dos EUA — Transações de ações divulgadas por deputados e senadores, com a data da transação e a data de divulgação pública (para que você possa medir o atraso na divulgação), o beneficiário efetivo da conta negociada (membro, cônjuge, filho dependente, conjunta ou um código de conta) e valores apresentados normalizados para os intervalos estatutários da Lei STOCK, com o registro original preservado
  • Lobby corporativo — Registros de lobby com registrante, receita, despesas e códigos de assunto
  • Transações de insiders — Registros do Formulário 4 da SEC mostrando compras e vendas de executivos
  • Classificações de analistas — Cobertura de Wall Street e mudanças de preço-alvo

O que você obtém

  • ⚡️ Servidor MCP local (sem proxy) usando sua própria chave de API da FinBrain

  • 🧰 Ferramentas (JSON por padrão, CSV opcional) com paginação

    • health

    • available_markets, available_tickers, available_regions

    • predictions_by_market, predictions_by_ticker

    • news_by_ticker, news_sentiment_by_ticker

    • app_ratings_by_ticker

    • analyst_ratings_by_ticker

    • house_trades_by_ticker, senate_trades_by_ticker

    • corporate_lobbying_by_ticker

    • insider_transactions_by_ticker

    • linkedin_metrics_by_ticker

    • options_put_call

    • reddit_mentions_by_ticker

    • government_contracts_by_ticker

    • patent_filings_by_ticker

    • recent_news, recent_analyst_ratings

    • screener_sentiment, screener_analyst_ratings, screener_news

    • screener_insider_trading, screener_house_trades, screener_senate_trades

    • screener_put_call_ratio, screener_linkedin, screener_app_ratings, screener_reddit_mentions, screener_government_contracts, screener_patent_filings

  • 🧹 Formatos consistentes e amigáveis para modelos (normalizamos as respostas brutas da API)

  • 📱 app_ratings_by_ticker retorna um series combinado — uma linha por data, carregando o maior aplicativo da empresa em cada loja — além de apps, um resumo de todos os aplicativos que ela publica (platform, app_id, app_name, observation_count, latest_score, latest_ratings_count) e app_count. Uma empresa pode publicar muitos aplicativos (a Apple tem 140 no iOS), então responder a uma pergunta por aplicativo a partir de series descreveria um aplicativo como se cobrisse a empresa inteira: leia apps para ver o que existe e depois passe app_id para obter as observações desse aplicativo específico. O resumo não carrega observações por design — o histórico de 140 aplicativos inundaria o contexto. app_id é null em linhas anteriores à chave por aplicativo (a plataforma é conhecida, o aplicativo não é), e um app_id desconhecido retorna available_app_ids em vez de uma série vazia

  • 🏛️ As linhas de insider_transactions_by_ticker, government_contracts_by_ticker, corporate_lobbying_by_ticker e patent_filings_by_ticker carregam cik — a Chave de Índice Central da SEC da empresa na data do registro, uma string de 10 dígitos preenchida com zeros ("0000320193"; mantenha como texto, os zeros à esquerda fazem parte do identificador), null quando o registro não tem resolução de entidade. Use-a para unir linhas a conjuntos de dados com chave da SEC (registros EDGAR, participações 13F) ou a um cadastro de títulos

  • 🔑 Forneça sua chave de API por meio da variável de ambiente FINBRAIN_API_KEY (uma variável de ambiente do shell ou o bloco env do seu cliente MCP)

Instalação

Opção A — Instalação padrão (pip)

# macOS / Linux / Windows
pip install --upgrade finbrain-mcp

Opção B — Instalação de desenvolvimento (editável)

# from repo root
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
pip install -e ".[dev]"

Mantenha o pip (produção) e seu venv (desenvolvimento) separados para evitar confusão de caminhos.

Opção C — Docker

# Build the image
docker build -t finbrain-mcp:latest .

# Run with your API key
docker run --rm -e FINBRAIN_API_KEY="YOUR_KEY" finbrain-mcp:latest

Consulte DOCKER.md para instruções detalhadas de uso do Docker.

Configure sua chave de API da FinBrain

A) No arquivo de configuração do seu cliente MCP (recomendado / mais confiável)

Coloque a chave diretamente na entrada do servidor MCP que seu cliente usa (Claude Desktop ou uma extensão MCP do VS Code). Isso garante que o servidor iniciado a veja, mesmo que as variáveis de ambiente do sistema não sejam detectadas.

Claude Desktop (instalação via pip)

{
  "mcpServers": {
    "finbrain": {
      "command": "finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

B) Variável de ambiente

Isso também funciona, mas observe que você deve reiniciar o cliente após defini-la para que o novo valor seja herdado.

# macOS/Linux
export FINBRAIN_API_KEY="YOUR_KEY"

# Windows (PowerShell, current session)
$env:FINBRAIN_API_KEY="YOUR_KEY"

# Windows (persistent for new processes)
setx FINBRAIN_API_KEY "YOUR_KEY"
# then fully quit and reopen your MCP client (e.g., Claude Desktop)

Dica: Se o caminho da variável de ambiente não parecer funcionar (comum no Windows se o cliente já estiver em execução), use o método JSON de configuração env acima — é mais determinístico.

Execute o servidor

Observação: Normalmente você não precisa executar o servidor manualmente — seu cliente MCP (Claude/VS Code) o inicia automaticamente. Use os comandos abaixo apenas para verificações manuais ou depuração.

  • Se instalado (pip):

    finbrain-mcp

  • De um venv de desenvolvimento:

    python -m finbrain_mcp.server

Verificação rápida de integridade sem um cliente MCP:

python - <<'PY'
import json
from finbrain_mcp.tools.health import health
print(json.dumps(health(), indent=2))
PY

Conecte um cliente de IA

Nenhuma inicialização manual necessária: O Claude Desktop e o VS Code iniciarão o servidor MCP para você com base na sua configuração. Você só precisa executar finbrain-mcp para verificações rápidas de sanidade ou depuração.

Claude Desktop

Edite sua configuração:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Instalação via pip (pacote publicado):

{
  "mcpServers": {
    "finbrain": {
      "command": "finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Dica para macOS (caminho completo):

Se "command": "finbrain-mcp" não funcionar, encontre o caminho absoluto e use-o.

which finbrain-mcp    # macOS/Linux
# (Windows: where finbrain-mcp)

Configuração do Claude com caminho completo (exemplo macOS):

{
  "mcpServers": {
    "finbrain": {
      "command": "/full/path/to/finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Venv de desenvolvimento (execute o módulo explicitamente):

{
  "mcpServers": {
    "finbrain-dev": {
      "command": "C:\\Users\\you\\path\\to\\repo\\.venv\\Scripts\\python.exe",
      "args": ["-m", "finbrain_mcp.server"],
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Docker:

{
  "mcpServers": {
    "finbrain": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "finbrain-mcp:latest"],
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

Após editar, saia e reabra o Claude.

VS Code (MCP)

  1. Abra a Paleta de Comandos → “MCP: Open User Configuration”.
    Isso abre seu mcp.json (perfil do usuário).

  2. Adicione o servidor sob a chave servers:

    {
  "servers": {
    "finbrain": {
      "command": "finbrain-mcp",
      "env": { "FINBRAIN_API_KEY": "YOUR_KEY" }
    }
  }
}

  3. No Copilot Chat, ative o Modo Agente para usar as ferramentas MCP.

O que você pode perguntar ao agente?

Você não precisa saber os nomes das ferramentas — basta perguntar em linguagem natural. Exemplos:

  • Previsões

    • “Obtenha as previsões diárias da FinBrain para AMZN.”
    • “Mostre previsões mensais (horizonte de 12 meses) para AMZN.”
    • “Obtenha previsões diárias de todo o mercado para os tickers do S&P 500.”

  • Notícias

    • “Obtenha artigos de notícias recentes para AMZN.”
    • “Qual é o sentimento das notícias para AMZN de 2025-01-01 a 2025-03-31 (limite 50)?”
    • “Mostre as notícias mais recentes de todas as ações do S&P 500.”

  • Avaliações de aplicativos

    • “Busque avaliações da app store para AMZN entre 2025-01-01 e 2025-06-30.”

  • Classificações de analistas

    • “Liste classificações de analistas para AMZN no 1º trimestre de 2025.”

  • Negociações do Congresso

    • “Mostre negociações recentes da Câmara envolvendo AMZN.”
    • “Mostre negociações recentes do Senado envolvendo META.”
    • “Para negociações da Câmara de NVDA, quanto tempo cada membro levou para divulgar a negociação?”
    • “Quais negociações recentes do Senado foram feitas por meio de uma conta de cônjuge ou conjunta?”

  • Lobby corporativo

    • “Mostre registros de lobby corporativo para AAPL.”
    • “Quais empresas de lobby a MSFT usou em 2024 (de 2024-01-01 a 2024-12-31)?”

  • Transações de insiders

    • “Transações de insiders recentes para AMZN?”

  • Métricas do LinkedIn

    • “Obtenha contagens de funcionários e seguidores do LinkedIn para AMZN (últimos 12 meses).”

  • Opções (put/call)

    • “Qual é o índice put/call para AMZN nos últimos 60 dias?”

  • Menções no Reddit

    • “Mostre menções no Reddit para TSLA na última semana.”
    • “Quais subreddits estão falando mais sobre AAPL?”

  • Contratos governamentais

    • “Mostre contratos governamentais concedidos à LMT em 2025.”
    • “Quais empresas têm as maiores concessões de contratos governamentais?”

  • Registros de patentes

    • “Mostre registros de patentes recentes para AAPL.”
    • “Quais empresas têm mais patentes concedidas recentemente?”

  • Triagens (entre tickers)

    • “Faça uma triagem de sentimento nas ações do S&P 500.”
    • “Mostre as classificações de analistas mais recentes em todas as ações.”
    • “Faça uma triagem de negociações de insiders em todos os tickers (limite 50).”
    • “Faça uma triagem de dados do LinkedIn para ações da região EUA.”
    • “Quais são os tickers mais mencionados no Reddit agora?”
    • “Quais empresas estão registrando mais patentes agora?”

  • Disponibilidade

    • “Quais mercados estão disponíveis?”
    • “Liste os tickers no universo de previsões diárias.”
    • “Mostre as regiões disponíveis e seus mercados.”

Observações

  • Formato de data: YYYY-MM-DD.
  • Os endpoints de séries temporais retornam os N pontos mais recentes por padrão — diga “limite 200” para obter mais.
  • Horizonte de previsões: diário (10 dias) ou mensal (12 meses).
  • Diga “como CSV” para receber CSV em vez de JSON.
  • Não é necessário especificar um mercado — basta usar o símbolo do ticker diretamente.

Desenvolvimento

# setup
python -m venv .venv
source .venv/bin/activate # Windows: .\.venv\Scripts\activate
pip install -e ".[dev]"  # run tests pytest -q

Estrutura do projeto (alto nível)

finbrain-mcp
├─ README.md
├─ pyproject.toml
├─ LICENSE
├─ .github/
├─ examples/
├─ src/
│  └─ finbrain_mcp/
│     ├─ __init__.py
│     ├─ server.py                # MCP server entrypoint
│     ├─ registry.py              # FastMCP instance
│     ├─ client_adapter.py        # wraps finbrain-python; caches SDK client; calls normalizers
│     ├─ auth.py                  # resolves API key (env var)
│     ├─ utils.py                 # helpers (latest_slice, CSV, DF->records)
│     ├─ normalizers/             # endpoint-specific shapers
│     └─ tools/                   # MCP tool functions (registered & testable)
└─ tests/                         # pytest suite with a fake SDK

Solução de problemas

  • ENOENT (não é possível iniciar o servidor)

    • Caminho errado na configuração do cliente. Use o caminho exato do venv:

      • …\.venv\Scripts\python.exe + ["-m","finbrain_mcp.server"], ou

      • …\.venv\Scripts\finbrain-mcp.exe

  • FinBrain API key not configured

    • Coloque FINBRAIN_API_KEY no bloco env do cliente ou

    • setx FINBRAIN_API_KEY "YOUR_KEY" e reinicie completamente o cliente.

  • Misturando instalações de desenvolvimento e produção

    • Mantenha o pip (produção) e o venv (desenvolvimento) separados.

    • Nas configurações, aponte para um ou outro — não ambos.

Licença

MIT (consulte LICENSE).

Agradecimentos

  • Construído sobre o Model Context Protocol e FastMCP.

  • Usa o SDK oficial finbrain-python.

© 2026 FinBrain Technologies — Feito com ❤️ para a comunidade quant.