Robinhood Portfolio Advisor
Read-only access to your Robinhood portfolio via the robinhood-mcp server. Provides live data for positions, quotes, fundamentals, news, earnings, analyst ratings, dividends, and options.
Prerequisites
1. Robinhood Account
You need a Robinhood account (free at robinhood.com).
2. MCP Server Installation
The robinhood-mcp package provides the MCP server. Install it with one of:
# Recommended — runs via uvx (no global install needed, auto-managed)
# Just add to your agent config and it works. uvx installs it on first run.
# Alternative — global pip install
pip install robinhood-mcp
Note:
uvxis provided by the uv Python package manager. Install it first:curl -LsSf https://astral.sh/uv/install.sh | sh
3. Environment Variables
Set these in your agent's .env file or shell profile:
| Variable | Required | Description |
|---|---|---|
ROBINHOOD_USERNAME | Yes | Your Robinhood email |
ROBINHOOD_PASSWORD | Yes | Your Robinhood password |
ROBINHOOD_TOTP_SECRET | Only if using authenticator app | The TOTP secret from your authenticator setup. Not needed if using SMS verification. |
4. Agent Configuration
See the templates/ directory for copy-paste config snippets for your agent. Quick reference:
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}" # Uncomment for authenticator app
timeout: 60
connect_timeout: 30
Other agents — see templates/ directory for Claude Desktop, Claude Code, Codex, OpenCode, Cline, and Windsurf.
After adding config, restart your agent. Verify with: hermes mcp test robinhood (Hermes) or check your agent's MCP status.
Available MCP Tools
These tools are registered as mcp_robinhood_* in Hermes Agent (prefix varies by agent):
| Tool | Description |
|---|---|
robinhood_get_portfolio | Portfolio value, equity, buying power, day change |
robinhood_get_positions | All holdings with cost basis, current value, P&L |
robinhood_get_position | Single holding by ticker (faster for one symbol) |
robinhood_get_watchlist | Stocks in your watchlists |
robinhood_get_quote | Real-time price, bid/ask, volume |
robinhood_get_fundamentals | P/E ratio, market cap, dividend yield, 52-week range |
robinhood_get_historicals | OHLCV price history (5min, 10min, hour, day, week) |
robinhood_get_news | Recent news articles for a symbol |
robinhood_get_earnings | Earnings dates, EPS estimates, actuals |
robinhood_get_ratings | Analyst buy/hold/sell ratings |
robinhood_get_dividends | Dividend payment history |
robinhood_get_options_positions | Current options positions |
robinhood_search_symbols | Search stocks by name or ticker |
Local Cache
Portfolio data is cached locally at ~/.hermes/data/robinhood/portfolio_cache.json (Hermes) or ~/.robinhood-mcp/cache.json (other agents).
Cache-First Strategy
Always check the cache first. Only call MCP tools when:
- Cache is older than 15 minutes AND the user needs live data
- User explicitly asks for a refresh ("refresh my portfolio", "get latest prices")
- User asks about a specific ticker not in cache
- User asks for rapidly changing data (news, real-time quotes)
Updating the Cache
# Hermes Agent users
python3 scripts/refresh_cache.py
# With custom paths
python3 scripts/refresh_cache.py --cache-dir ~/my-data --vault-path ~/my-vault
# JSON output only (no Obsidian)
python3 scripts/refresh_cache.py --json-only
# Force refresh even if cache is fresh
python3 scripts/refresh_cache.py --force
The agent can also update the cache inline during any portfolio query by calling MCP tools and writing results to the cache file.
Portfolio Query Workflow
When the user asks about their portfolio:
- Read cache for context (portfolio value, positions, allocations)
- If data is stale (>15 min) or user wants live data, call MCP tools
- Update cache after any MCP fetch
- Answer with context of their actual holdings — not generic advice
- Reference their cost basis, unrealized P&L, and allocation when relevant
- For options questions, cross-reference with the user's strategy if known
When the user asks about a specific ticker:
- Check if
wiki/entities/<ticker>.mdexists (if using Obsidian) - Read it for existing thesis and research history
- Fetch live data (quote, fundamentals, news, ratings) via MCP
- Respond with synthesis of wiki knowledge + live data
- Append a Research Notes entry to the entity page (if using Obsidian)
- If ticker not in portfolio, track it in a research queue
When to Use MCP vs Cache
| Scenario | Use |
|---|---|
| "What's my portfolio worth?" | Cache (if fresh enough) |
| "How's my NVDA doing?" | Cache first, MCP if stale or ticker missing |
| "Give me a full portfolio update" | MCP (always get live data) |
| "Any news on TSLA?" | MCP (news changes constantly) |
| "What are analyst ratings for AAPL?" | MCP (research data is always live) |
| "Show me my options positions" | Cache first, MCP if stale |
| "What dividends have I received?" | Cache first |
| "Refresh my data" | MCP then update cache |
Research-to-Entity Workflow (Optional — Requires Obsidian)
Problem: Research queries about stocks get lost in chat sessions. Solution: Every holding or researched ticker gets a persistent entity page. Research is appended, not forgotten.
Entity Page Structure
Each ticker gets a page at wiki/entities/<ticker>.md:
---
title: Company Name
created: YYYY-MM-DD
updated: YYYY-MM-DD
type: entity
tags: [ticker, sector, ...]
---
# Company Name (TICKER)
Brief overview...
## Key Facts
...
## Investment Thesis
...
## Position History
> Updated automatically. Do not edit manually.
### Current Position
| Metric | Value |
|--------|-------|
| Quantity | 50 |
| Avg Cost | $40.69 |
| Current Price | $45.20 |
| Total Return | +10.8% |
### Position Updates
- **[2026-04-24]** 50 shares @ $40.69 avg
## Research Notes
> Agent appends dated entries after each research query.
### [2026-04-24] Should I add to HIMS at $30?
Key points: [bullet summary]
Decision: [if user stated one]
When to Update Entity Pages
- On every portfolio pull — Update position data for each holding
- After every research query — Append a dated Research Notes entry
- When creating a new entity — Fetch fundamentals, create page, add to wiki index
Research Queue
wiki/concepts/research-queue.md tracks tickers being evaluated but not yet purchased:
| Ticker | Source | Thesis (1-line) | Status | Added | Notes |
|---|---|---|---|---|---|
| ABC | YouTube video | EV battery play | researching | 2026-04-24 | Mentioned by MKBHD |
Status values: researching → ready to buy → (removed when purchased) or passed
Obsidian Vault Integration (Optional)
Every portfolio pull can write two files to your Obsidian vault:
| File | Behavior |
|---|---|
_ephemeral/portfolio/snapshots/YYYY-MM-DD-HHMM.md | Immutable — one per pull, full data |
_ephemeral/portfolio/latest.md | Overwritten — current state + deltas vs previous |
Frontmatter for Dataview
Both files include YAML frontmatter:
---
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
---
This enables Dataview queries like:
TABLE date, total_equity, day_change_pct
FROM "_ephemeral/portfolio/snapshots"
SORT snapshot_time DESC
Delta Computation
The latest.md compares against the most recent snapshot and highlights:
- 🆕 New positions (bought since last pull)
- ❌ Closed positions (sold since last pull)
- 📊 Significant moves (>5% price change OR >1% allocation shift)
- Equity change since last snapshot
To enable Obsidian integration, set the --vault-path argument when running refresh_cache.py, or set the ROBINHOOD_VAULT_PATH environment variable.
Advisory Guidelines
- Always answer with context of the user's actual holdings — not generic advice
- Reference cost basis, unrealized P&L, and allocation percentages when relevant
- For options questions, understand the user's strategy (e.g., 0DTE breakout)
- When recommending actions, show the math (current allocation, risk/reward)
- Never suggest trades unless the user explicitly asks for recommendations
- Flag concentration risk when a single position exceeds 20% of portfolio
- Cross-reference news with fundamentals — don't react to headlines alone
Security & Privacy
- No credentials stored in the skill — auth is via environment variables in MCP config
- Read-only access — the MCP server cannot execute trades or modify account settings
- Local processing — credentials are used locally to authenticate; session tokens cached in
~/.tokens/robinhood.pickle - Cache is local only —
~/.hermes/data/robinhood/is never transmitted - Obsidian vault — snapshots are written to the user's local vault only
Troubleshooting
| Issue | Solution |
|---|---|
| "Not logged in" | Verify ROBINHOOD_USERNAME and ROBINHOOD_PASSWORD env vars are set correctly |
| "Non-base32 digit found" | ROBINHOOD_TOTP_SECRET contains invalid characters — only A-Z and digits 2-7. Remove this var if using SMS verification |
| Rate limiting (429 errors) | robin_stocks has no built-in rate limiting. Pause activity for several minutes and retry |
| MCP server won't start | Ensure uvx is installed (pip install uv or curl -LsSf https://astral.sh/uv/install.sh | sh). Run uvx robinhood-mcp manually to test |
| Cache script fails | Ensure robin_stocks and pyotp are installed: pip install robin_stocks pyotp |
| Stale quotes | Robinhood quotes are point-in-time, not live streaming. Refresh via MCP for latest data |
Related
- robinhood-mcp — The underlying MCP server
- robin_stocks — Unofficial Robinhood API wrapper
portfolio-obsidian-bridge— Generic Obsidian sync for any brokeragellm-wiki— Wiki architecture for persistent researchobsidian— Obsidian vault operations