Consultor de Portfólio Robinhood
Acesso somente leitura ao seu portfólio da Robinhood através do servidor robinhood-mcp. Fornece dados ao vivo para posições, cotações, fundamentos, notícias, lucros, classificações de analistas, dividendos e opções.
Pré-requisitos
1. Conta Robinhood
Você precisa de uma conta Robinhood (gratuita em robinhood.com).
2. Instalação do Servidor MCP
O pacote robinhood-mcp fornece o servidor MCP. Instale-o com um dos seguintes comandos:
# Recomendado — executa via uvx (sem instalação global necessária, gerenciado automaticamente)
# Basta adicionar à configuração do seu agente e funciona. uvx o instala na primeira execução.
# Alternativa — instalação global com pip
pip install robinhood-mcp
Nota:
uvxé fornecido pelo gerenciador de pacotes Python uv. Instale-o primeiro:curl -LsSf https://astral.sh/uv/install.sh | sh
3. Variáveis de Ambiente
Defina estas variáveis no arquivo .env do seu agente ou no perfil do shell:
| Variável | Obrigatória | Descrição |
|---|---|---|
ROBINHOOD_USERNAME | Sim | Seu email da Robinhood |
ROBINHOOD_PASSWORD | Sim | Sua senha da Robinhood |
ROBINHOOD_TOTP_SECRET | Apenas se usar aplicativo autenticador | O segredo TOTP da sua configuração de autenticador. Não necessário se usar verificação por SMS. |
4. Configuração do Agente
Consulte o diretório templates/ para trechos de configuração prontos para copiar e colar no seu agente. Referência rápida:
Hermes Agent (~/.hermes/config.yaml):
mcp_servers:
robinhood:
command: uvx
args:
- robinhood-mcp
env:
ROBINHOOD_USERNAME: "${ROBINHOOD_USERNAME}"
ROBINHOOD_PASSWORD: "${ROBINHOOD_PASSWORD}"
# ROBINHOOD_TOTP_SECRET: "${ROBINHOOD_TOTP_SECRET}" # Descomente para aplicativo autenticador
timeout: 60
connect_timeout: 30
Outros agentes — consulte o diretório templates/ para Claude Desktop, Claude Code, Codex, OpenCode, Cline e Windsurf.
Após adicionar a configuração, reinicie seu agente. Verifique com: hermes mcp test robinhood (Hermes) ou verifique o status MCP do seu agente.
Ferramentas MCP Disponíveis
Estas ferramentas são registradas como mcp_robinhood_* no Hermes Agent (o prefixo varia conforme o agente):
| Ferramenta | Descrição |
|---|---|
robinhood_get_portfolio | Valor do portfólio, patrimônio líquido, poder de compra, variação do dia |
robinhood_get_positions | Todas as participações com custo médio, valor atual, lucro/perda |
robinhood_get_position | Participação única por ticker (mais rápido para um símbolo) |
robinhood_get_watchlist | Ações em suas listas de observação |
robinhood_get_quote | Preço em tempo real, compra/venda, volume |
robinhood_get_fundamentals | Índice P/L, capitalização de mercado, rendimento de dividendos, faixa de 52 semanas |
robinhood_get_historicals | Histórico de preços OHLCV (5min, 10min, hora, dia, semana) |
robinhood_get_news | Artigos de notícias recentes para um símbolo |
robinhood_get_earnings | Datas de lucros, estimativas de EPS, valores reais |
robinhood_get_ratings | Classificações de analistas: compra/manutenção/venda |
robinhood_get_dividends | Histórico de pagamentos de dividendos |
robinhood_get_options_positions | Posições atuais em opções |
robinhood_search_symbols | Pesquisar ações por nome ou ticker |
Cache Local
Os dados do portfólio são armazenados em cache localmente em ~/.hermes/data/robinhood/portfolio_cache.json (Hermes) ou ~/.robinhood-mcp/cache.json (outros agentes).
Estratégia de Cache Prioritário
Sempre verifique o cache primeiro. Só chame as ferramentas MCP quando:
- O cache tiver mais de 15 minutos E o usuário precisar de dados ao vivo
- O usuário solicitar explicitamente uma atualização ("atualizar meu portfólio", "obter preços mais recentes")
- O usuário perguntar sobre um ticker específico que não está no cache
- O usuário solicitar dados que mudam rapidamente (notícias, cotações em tempo real)
Atualizando o Cache
# Usuários do Hermes Agent
python3 scripts/refresh_cache.py
# Com caminhos personalizados
python3 scripts/refresh_cache.py --cache-dir ~/meus-dados --vault-path ~/meu-cofre
# Apenas saída JSON (sem Obsidian)
python3 scripts/refresh_cache.py --json-only
# Forçar atualização mesmo se o cache estiver fresco
python3 scripts/refresh_cache.py --force
O agente também pode atualizar o cache inline durante qualquer consulta ao portfólio, chamando as ferramentas MCP e escrevendo os resultados no arquivo de cache.
Fluxo de Consulta ao Portfólio
Quando o usuário perguntar sobre seu portfólio:
- Leia o cache para obter contexto (valor do portfólio, posições, alocações)
- Se os dados estiverem desatualizados (>15 min) ou o usuário quiser dados ao vivo, chame as ferramentas MCP
- Atualize o cache após qualquer busca MCP
- Responda com contexto de suas participações reais — não conselhos genéricos
- Refira-se ao custo médio, lucro/prejuízo não realizado e alocação quando relevante
- Para perguntas sobre opções, faça referência cruzada com a estratégia do usuário, se conhecida
Quando o usuário perguntar sobre um ticker específico:
- Verifique se o arquivo
wiki/entities/<ticker>.mdexiste (se estiver usando Obsidian) - Leia-o para obter a tese existente e o histórico de pesquisa
- Busque dados ao vivo (cotação, fundamentos, notícias, classificações) via MCP
- Responda com uma síntese do conhecimento da wiki + dados ao vivo
- Adicione uma entrada de Notas de Pesquisa à página da entidade (se estiver usando Obsidian)
- Se o ticker não estiver no portfólio, rastreie-o em uma fila de pesquisa
Quando Usar MCP vs Cache
| Cenário | Uso |
|---|---|
| "Quanto vale meu portfólio?" | Cache (se suficientemente fresco) |
| "Como está minha NVDA?" | Cache primeiro, MCP se desatualizado ou ticker ausente |
| "Me dê uma atualização completa do portfólio" | MCP (sempre obtenha dados ao vivo) |
| "Alguma notícia sobre a TSLA?" | MCP (notícias mudam constantemente) |
| "Quais são as classificações dos analistas para AAPL?" | MCP (dados de pesquisa são sempre ao vivo) |
| "Mostre minhas posições em opções" | Cache primeiro, MCP se desatualizado |
| "Quais dividendos recebi?" | Cache primeiro |
| "Atualize meus dados" | MCP e depois atualize o cache |
Fluxo de Pesquisa para Entidade (Opcional — Requer Obsidian)
Problema: Consultas de pesquisa sobre ações se perdem em sessões de chat. Solução: Cada participação ou ticker pesquisado ganha uma página de entidade persistente. A pesquisa é anexada, não esquecida.
Estrutura da Página de Entidade
Cada ticker recebe uma página em wiki/entities/<ticker>.md:
---
title: Nome da Empresa
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: entity
tags: [ticker, setor, ...]
---
# Nome da Empresa (TICKER)
Breve visão geral...
## Fatos Principais
...
## Tese de Investimento
...
## Histórico de Posição
> Atualizado automaticamente. Não edite manualmente.
### Posição Atual
| Métrica | Valor |
|---------|-------|
| Quantidade | 50 |
| Custo Médio | R$ 40,69 |
| Preço Atual | R$ 45,20 |
| Retorno Total | +10,8% |
### Atualizações de Posição
- **[2026-04-24]** 50 ações @ média R$ 40,69
## Notas de Pesquisa
> O agente adiciona entradas datadas após cada consulta de pesquisa.
### [2026-04-24] Devo adicionar HIMS a R$ 30?
Pontos principais: [resumo em tópicos]
Decisão: [se o usuário declarou uma]
Quando Atualizar Páginas de Entidade
- Em cada extração de portfólio — Atualize os dados de posição para cada participação
- Após cada consulta de pesquisa — Adicione uma entrada de Notas de Pesquisa datada
- Ao criar uma nova entidade — Busque fundamentos, crie a página, adicione ao índice da wiki
Fila de Pesquisa
wiki/concepts/research-queue.md rastreia tickers sendo avaliados mas ainda não comprados:
| Ticker | Fonte | Tese (1 linha) | Status | Adicionado | Notas |
|---|---|---|---|---|---|
| ABC | Vídeo no YouTube | Jogada de baterias EV | pesquisando | 2026-04-24 | Mencionado por MKBHD |
Valores de status: pesquisando → pronto para comprar → (removido quando comprado) ou passou
Integração com Cofre Obsidian (Opcional)
Cada extração de portfólio pode escrever dois arquivos em seu cofre Obsidian:
| Arquivo | Comportamento |
|---|---|
_ephemeral/portfolio/snapshots/YYYY-MM-DD-HHMM.md | Imutável — um por extração, dados completos |
_ephemeral/portfolio/latest.md | Sobrescrito — estado atual + deltas em relação ao anterior |
Frontmatter para Dataview
Ambos os arquivos incluem frontmatter YAML:
---
snapshot_time: 2026-04-24T18:58:02Z
date: 2026-04-24
time: 14:58
total_equity: 42700.94
day_change: -834.73
day_change_pct: -1.92
positions_count: 16
options_count: 1
dividends_ytd: 1.68
type: portfolio-snapshot
---
Isso permite consultas Dataview como:
TABLE date, total_equity, day_change_pct
FROM "_ephemeral/portfolio/snapshots"
SORT snapshot_time DESC
Cálculo de Delta
O arquivo latest.md compara com o snapshot mais recente e destaca:
- 🆕 Novas posições (compradas desde a última extração)
- ❌ Posições fechadas (vendidas desde a última extração)
- 📊 Movimentos significativos (>5% de variação de preço OU >1% de mudança na alocação)
- Mudança no patrimônio desde o último snapshot
Para ativar a integração com Obsidian, defina o argumento --vault-path ao executar refresh_cache.py, ou defina a variável de ambiente ROBINHOOD_VAULT_PATH.
Diretrizes de Consultoria
- Sempre responda com contexto das participações reais do usuário — não conselhos genéricos
- Refira-se ao custo médio, lucro/prejuízo não realizado e percentuais de alocação quando relevante
- Para perguntas sobre opções, entenda a estratégia do usuário (ex.: breakout 0DTE)
- Ao recomendar ações, mostre os números (alocação atual, risco/recompensa)
- Nunca sugira negociações a menos que o usuário peça explicitamente recomendações
- Sinalize risco de concentração quando uma única posição exceder 20% do portfólio
- Faça referência cruzada de notícias com fundamentos — não reaja apenas a manchetes
Segurança e Privacidade
- Nenhuma credencial armazenada no skill — a autenticação é feita via variáveis de ambiente na configuração MCP
- Acesso somente leitura — o servidor MCP não pode executar negociações ou modificar configurações da conta
- Processamento local — as credenciais são usadas localmente para autenticar; tokens de sessão armazenados em cache em
~/.tokens/robinhood.pickle - Cache é apenas local —
~/.hermes/data/robinhood/nunca é transmitido - Cofre Obsidian — snapshots são gravados apenas no cofre local do usuário
Solução de Problemas
| Problema | Solução |
|---|---|
| "Não está logado" | Verifique se as variáveis de ambiente ROBINHOOD_USERNAME e ROBINHOOD_PASSWORD estão definidas corretamente |
| "Dígito não-base32 encontrado" | ROBINHOOD_TOTP_SECRET contém caracteres inválidos — apenas A-Z e dígitos 2-7. Remova esta variável se estiver usando verificação por SMS |
| Limitação de taxa (erros 429) | robin_stocks não tem limitação de taxa embutida. Pause a atividade por vários minutos e tente novamente |
| Servidor MCP não inicia | Certifique-se de que uvx está instalado (pip install uv ou `curl -LsSf https://astral.sh/uv/install.sh |
| Script de cache falha | Certifique-se de que robin_stocks e pyotp estão instalados: pip install robin_stocks pyotp |
| Cotações desatualizadas | As cotações da Robinhood são pontuais, não em streaming ao vivo. Atualize via MCP para obter os dados mais recentes |
Relacionados
- robinhood-mcp — O servidor MCP subjacente
- robin_stocks — Wrapper não oficial da API Robinhood
portfolio-obsidian-bridge— Sincronização Obsidian genérica para qualquer corretorallm-wiki— Arquitetura de wiki para pesquisa persistenteobsidian— Operações de cofre Obsidian