Robinhood

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: uvx is 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:

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):

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:

1. Cache is older than 15 minutes AND the user needs live data
2. User explicitly asks for a refresh ("refresh my portfolio", "get latest prices")
3. User asks about a specific ticker not in cache
4. 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:

1. Read cache for context (portfolio value, positions, allocations)
2. If data is stale (>15 min) or user wants live data, call MCP tools
3. Update cache after any MCP fetch
4. Answer with context of their actual holdings — not generic advice
5. Reference their cost basis, unrealized P&L, and allocation when relevant
6. For options questions, cross-reference with the user's strategy if known

When the user asks about a specific ticker:

1. Check if wiki/entities/<ticker>.md exists (if using Obsidian)
2. Read it for existing thesis and research history
3. Fetch live data (quote, fundamentals, news, ratings) via MCP
4. Respond with synthesis of wiki knowledge + live data
5. Append a Research Notes entry to the entity page (if using Obsidian)
6. If ticker not in portfolio, track it in a research queue

When to Use MCP vs 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

1. On every portfolio pull — Update position data for each holding
2. After every research query — Append a dated Research Notes entry
3. 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:

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:

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

1. Always answer with context of the user's actual holdings — not generic advice
2. Reference cost basis, unrealized P&L, and allocation percentages when relevant
3. For options questions, understand the user's strategy (e.g., 0DTE breakout)
4. When recommending actions, show the math (current allocation, risk/reward)
5. Never suggest trades unless the user explicitly asks for recommendations
6. Flag concentration risk when a single position exceeds 20% of portfolio
7. 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

Related

• robinhood-mcp — The underlying MCP server
• robin_stocks — Unofficial Robinhood API wrapper
• portfolio-obsidian-bridge — Generic Obsidian sync for any brokerage
• llm-wiki — Wiki architecture for persistent research
• obsidian — Obsidian vault operations