robinhood-mcp

A read-only MCP server for Robinhood portfolio research. Wraps robin_stocks to give AI assistants access to your portfolio data for analysis.

⚠️ Research Tool Only - This server provides read-only access. No trading functionality is exposed.

⚠️ Unofficial API - Uses robin_stocks unofficial API. May break without notice. Use at your own risk.

What Can You Do With This?

Once connected, you can have natural conversations with Claude about your portfolio:

Portfolio Health Check

"Give me a health check on my portfolio. What's my total value, sector concentration, and any positions that are significantly up or down?"

Claude will pull your positions, calculate sector exposure, identify your best and worst performers, and flag any concentration risks.

Research Before Buying

"I'm thinking about adding to my NVDA position. Show me the fundamentals, recent news, analyst ratings, and how it's performed over the past year."

Get comprehensive research combining price history, P/E ratios, earnings dates, and analyst sentiment in one response.

Compare Investments

"Compare the cruise lines in my portfolio - show me CCL, RCL, and NCLH side by side with their P/E ratios, market caps, and year-to-date performance."

Quickly evaluate similar holdings to identify relative value.

Dividend Analysis

"What dividends have I received this year? Which of my holdings pay dividends and what are their yields?"

Track your passive income and identify dividend opportunities in your portfolio.

Risk Assessment

"What's my exposure to the energy sector? How concentrated am I in my top 5 holdings?"

Analyze sector concentration and identify positions that might be overweight.

Earnings Calendar

"Which of my holdings have earnings coming up in the next two weeks?"

Stay ahead of earnings volatility with a personalized calendar.

Performance Attribution

"Break down my portfolio returns. What's driving my gains and losses?"

Understand which positions are contributing most to your performance.

Trade History

"Show me my HIMS order history - every buy and sell with prices and dates."

Review the executed orders behind your positions, with per-fill detail useful for cost-basis and tax research.

Watchlist Research

"Pull quotes and fundamentals for everything in my watchlist. Which ones look interesting right now?"

Bulk research stocks you're tracking.

Installation

pip install robinhood-mcp

Or run directly with uvx:

uvx robinhood-mcp

Configuration

Environment Variables

export ROBINHOOD_USERNAME="your_email"
export ROBINHOOD_PASSWORD="your_password"
export ROBINHOOD_TOTP_SECRET="your_2fa_secret"          # if your account exposes TOTP (see below)
export ROBINHOOD_APPROVAL_TIMEOUT="60"                  # optional — seconds to wait for push approval

For Claude Desktop and other headless deployments, you have two paths:

1. TOTP, if your account exposes it. Set ROBINHOOD_TOTP_SECRET to the base32 authenticator-app secret (found at Account → Security → Two-Factor Authentication in the Robinhood mobile app or at robinhood.com). Login is fast, non-interactive, and survives restarts.
2. Push approval, otherwise. Leave ROBINHOOD_TOTP_SECRET unset. The first tool call after a restart triggers a push notification in the Robinhood mobile app — tap "Approve" within ROBINHOOD_APPROVAL_TIMEOUT seconds (default 60). After that one approval, the session is cached in ~/.tokens/robinhood.pickle and reused for days/weeks, with no further interaction until natural expiry.

Newer Robinhood accounts that use passkeys or biometric login as their primary 2FA may not surface a TOTP option in either the iOS app or web settings — push approval works fine for these accounts.

After an authentication failure the server caches the error for ~5 minutes so subsequent tool calls fail fast instead of re-blocking the MCP server while re-attempting the full login flow. Restart Claude Desktop to retry sooner.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "robinhood": {
      "command": "uvx",
      "args": ["robinhood-mcp"],
      "env": {
        "ROBINHOOD_USERNAME": "your_email",
        "ROBINHOOD_PASSWORD": "your_password"
      }
    }
  }
}

If your account has TOTP enrollment available, add "ROBINHOOD_TOTP_SECRET": "your_2fa_secret" to the env block above.

Claude Code

claude mcp add robinhood -- uvx robinhood-mcp

Available Tools

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	One holding by ticker with quantity, value, and P&L
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 (day/week/month/year)
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_get_order_history	Order history (buys/sells) with per-fill detail
robinhood_search_symbols	Search stocks by name or ticker

Example Conversations

Simple queries:

• "What's my portfolio worth right now?"
• "Show me my top 5 holdings by value"
• "Do I already own HIMS, and what's my current position?"
• "Get me a quote for AAPL"

For single-symbol portfolio questions, prefer robinhood_get_position over robinhood_get_positions. The single-symbol tool avoids rebuilding every holding and is much faster for questions like "Should I add more HIMS?"

Analysis requests:

• "Compare the fundamentals of GOOGL vs META"
• "Which of my stocks are trading below their 52-week average?"
• "Show me the price chart for TSLA over the past year"
• "What's my best performing stock? What's my worst?"

Research workflows:

• "I want to understand the cruise line industry. Pull data on CCL, RCL, and NCLH - compare their fundamentals and recent performance."
• "Find stocks in my portfolio with a P/E under 15 and positive earnings growth"
• "I'm down big on a few positions. Show me the fundamentals and news for my worst performers to help me decide if I should hold or cut losses."

Limitations

• Read-only: Cannot place trades, modify watchlists, or change account settings
• Unofficial API: Robinhood may change their API at any time, breaking functionality
• No real-time streaming: Quotes are point-in-time, not live feeds
• Session expiry: You may need to re-authenticate periodically
• Rate limits: Heavy usage may trigger Robinhood's rate limiting

Security Notes

• Credentials are only used locally to authenticate with Robinhood
• Session tokens are cached in ~/.tokens/robinhood.pickle by robin_stocks
• Never commit your .env file or expose credentials
• This tool cannot execute trades - it's read-only by design

Development

git clone https://github.com/verygoodplugins/robinhood-mcp.git
cd robinhood-mcp
pip install -e ".[dev]"

# Lint
ruff check . && ruff format --check .

# Test
pytest

# Run locally
robinhood-mcp

Troubleshooting

"Not logged in" errors:

• Verify your username and password are correct
• If you have 2FA with an authenticator app, you need ROBINHOOD_TOTP_SECRET
• Try logging in through the Robinhood app to ensure your account isn't locked
• Tool calls hang briefly then fail with "Login returned empty result": no cached session and no ROBINHOOD_TOTP_SECRET, so the server is waiting for you to approve a push notification in the Robinhood mobile app. Tap "Approve" within ROBINHOOD_APPROVAL_TIMEOUT seconds (default 60) and call the tool again — the session pickle is now cached and subsequent calls won't prompt. If TOTP is available on your account, adding ROBINHOOD_TOTP_SECRET removes the prompt entirely. After a failure the server caches the error for ~5 min; restart Claude Desktop to retry sooner.

"Non-base32 digit found" error:

• Your TOTP secret contains invalid characters
• The secret should only contain letters A-Z and digits 2-7
• If you don't use an authenticator app, remove ROBINHOOD_TOTP_SECRET entirely

Rate limiting:

• robin_stocks doesn't have built-in rate limiting
• If you hit rate limits, wait a few minutes before retrying

License

MIT

Disclaimer

This tool is for educational and research purposes only. It uses unofficial APIs that may break at any time. The authors are not responsible for any account restrictions, data inaccuracies, or financial losses.

This project is not affiliated with, endorsed by, or connected to Robinhood Markets, Inc.

Automation Examples

Daily Portfolio Review with Claude Code

Set up a cron job to get a daily portfolio briefing:

# ~/.claude/commands/portfolio-review.md
---
description: "Daily portfolio health check"
---
Using the robinhood MCP tools:
1. Get my current portfolio value and day change
2. Identify my top 3 gainers and top 3 losers today
3. Flag any positions that are down more than 20% from cost basis
4. Check if any holdings have earnings in the next 7 days
5. Give me a 2-3 sentence summary I can read with my morning coffee

Run it daily:

# Add to crontab -e
0 7 * * 1-5 cd ~/Projects && claude -p "/portfolio-review" --dangerously-skip-permissions >> ~/portfolio-reports/$(date +\%Y-\%m-\%d).md

Weekly Research Digest

# ~/.claude/commands/weekly-research.md
---
description: "Weekly deep dive on portfolio"
---
For each of my top 10 holdings by value:
1. Pull current fundamentals and compare to sector averages
2. Get recent news and analyst rating changes
3. Flag any significant changes from last week
4. Identify 2-3 stocks from my watchlist that might be worth adding

Format as a markdown report I can review on the weekend.

Credits

Built with 🧡 by Jack Arturo at Very Good Plugins.

Powered by robin_stocks and FastMCP.

Links

• GitHub
• PyPI
• Very Good Plugins
• AutoMem - AI memory infrastructure
• robin_stocks Documentation
• Model Context Protocol