{
"markdown": "\n\n# robinhood-mcp\n\n[](https://deepwiki.com/verygoodplugins/robinhood-mcp)\n[](https://badge.fury.io/py/robinhood-mcp)\n[](https://opensource.org/licenses/MIT)\n[](https://www.python.org/downloads/)\n[](https://modelcontextprotocol.io/)\n\nA read-only MCP server for Robinhood portfolio research. Wraps [robin_stocks](https://github.com/jmfernandes/robin_stocks) to give AI assistants access to your portfolio data for analysis.\n\n> **⚠️ Research Tool Only** - This server provides read-only access. No trading functionality is exposed.\n\n> **⚠️ Unofficial API** - Uses robin_stocks unofficial API. May break without notice. Use at your own risk.\n\n## Demo\n\n\n\nWatch the simulated product demo
\n\nThis demo uses simulated account data and a generic assistant interface. It shows read-only research workflows only; it does not show real credentials, real holdings, professional advice, or trade execution.\n\n## What Can You Do With This?\n\nOnce connected, you can have natural conversations with Claude about your portfolio:\n\n### Portfolio Health Check\n\n> \"Give me a health check on my portfolio. What's my total value, sector concentration, and any positions that are significantly up or down?\"\n\nClaude will pull your positions, calculate sector exposure, identify your best and worst performers, and flag any concentration risks.\n\n### Research Before Buying\n\n> \"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.\"\n\nGet comprehensive research combining price history, P/E ratios, earnings dates, and analyst sentiment in one response.\n\n### Compare Investments\n\n> \"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.\"\n\nQuickly evaluate similar holdings to identify relative value.\n\n### Dividend Analysis\n\n> \"What dividends have I received this year? Which of my holdings pay dividends and what are their yields?\"\n\nTrack your passive income and identify dividend opportunities in your portfolio.\n\n### Risk Assessment\n\n> \"What's my exposure to the energy sector? How concentrated am I in my top 5 holdings?\"\n\nAnalyze sector concentration and identify positions that might be overweight.\n\n### Earnings Calendar\n\n> \"Which of my holdings have earnings coming up in the next two weeks?\"\n\nStay ahead of earnings volatility with a personalized calendar.\n\n### Performance Attribution\n\n> \"Break down my portfolio returns. What's driving my gains and losses?\"\n\nUnderstand which positions are contributing most to your performance.\n\n### Trade History\n\n> \"Show me my HIMS order history - every buy and sell with prices and dates.\"\n\nReview the executed orders behind your positions, with per-fill detail useful for cost-basis and tax research.\n\n### Watchlist Research\n\n> \"Pull quotes and fundamentals for everything in my watchlist. Which ones look interesting right now?\"\n\nBulk research stocks you're tracking.\n\n## Installation\n\n```bash\npip install robinhood-mcp\n```\n\nOr run directly with uvx:\n\n```bash\nuvx robinhood-mcp\n```\n\n## Configuration\n\n### Environment Variables\n\n```bash\nexport ROBINHOOD_USERNAME=\"your_email\"\nexport ROBINHOOD_PASSWORD=\"your_password\"\nexport ROBINHOOD_TOTP_SECRET=\"your_2fa_secret\" # if your account exposes TOTP (see below)\nexport ROBINHOOD_APPROVAL_TIMEOUT=\"60\" # optional — seconds to wait for push approval\n```\n\n**For Claude Desktop and other headless deployments, you have two paths:**\n\n1. **TOTP, if your account exposes it.** Set `ROBINHOOD_TOTP_SECRET` to the\n base32 authenticator-app secret (found at *Account → Security → Two-Factor\n Authentication* in the Robinhood mobile app or at robinhood.com). Login is\n fast, non-interactive, and survives restarts.\n2. **Push approval, otherwise.** Leave `ROBINHOOD_TOTP_SECRET` unset. The\n first tool call after a restart triggers a push notification in the\n Robinhood mobile app — tap \"Approve\" within `ROBINHOOD_APPROVAL_TIMEOUT`\n seconds (default 60). After that one approval, the session is cached in\n `~/.tokens/robinhood.pickle` and reused for days/weeks, with no further\n interaction until natural expiry.\n\nNewer Robinhood accounts that use passkeys or biometric login as their primary\n2FA may not surface a TOTP option in either the iOS app or web settings —\npush approval works fine for these accounts.\n\nAfter an authentication failure the server caches the error for ~5 minutes so\nsubsequent tool calls fail fast instead of re-blocking the MCP server while\nre-attempting the full login flow. Restart Claude Desktop to retry sooner.\n\n### Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n \"mcpServers\": {\n \"robinhood\": {\n \"command\": \"uvx\",\n \"args\": [\"robinhood-mcp\"],\n \"env\": {\n \"ROBINHOOD_USERNAME\": \"your_email\",\n \"ROBINHOOD_PASSWORD\": \"your_password\"\n }\n }\n }\n}\n```\n\nIf your account has TOTP enrollment available, add\n`\"ROBINHOOD_TOTP_SECRET\": \"your_2fa_secret\"` to the `env` block above.\n\n### Claude Code\n\n```bash\nclaude mcp add robinhood -- uvx robinhood-mcp\n```\n\n## Available Tools\n\n| Tool | Description |\n| --------------------------------- | ---------------------------------------------------- |\n| `robinhood_get_accounts` | Account numbers for available Robinhood accounts |\n| `robinhood_get_portfolio` | Portfolio value, equity, buying power, day change |\n| `robinhood_get_positions` | All holdings with cost basis, current value, P&L |\n| `robinhood_get_position` | One holding by ticker with quantity, value, and P&L |\n| `robinhood_get_watchlist` | Stocks in your watchlists |\n| `robinhood_get_quote` | Real-time price, bid/ask, volume |\n| `robinhood_get_fundamentals` | P/E ratio, market cap, dividend yield, 52-week range |\n| `robinhood_get_historicals` | OHLCV price history (day/week/month/year) |\n| `robinhood_get_news` | Recent news articles for a symbol |\n| `robinhood_get_earnings` | Earnings dates, EPS estimates, actuals |\n| `robinhood_get_ratings` | Analyst buy/hold/sell ratings |\n| `robinhood_get_dividends` | Dividend payment history |\n| `robinhood_get_options_positions` | Current options positions |\n| `robinhood_get_order_history` | Order history (buys/sells) with per-fill detail |\n| `robinhood_search_symbols` | Search stocks by name or ticker |\n\n### Account Selection\n\nIf your Robinhood login has multiple accounts, call `robinhood_get_accounts`\nfirst and pass the returned `account_number` to account-scoped tools. Omit\n`account_number` to use Robinhood's default account.\n\nTools with optional `account_number` support:\n\n- `robinhood_get_portfolio`\n- `robinhood_get_positions`\n- `robinhood_get_position`\n- `robinhood_get_dividends`\n- `robinhood_get_options_positions`\n- `robinhood_get_order_history`\n\n## Example Conversations\n\n**Simple queries:**\n\n- \"What's my portfolio worth right now?\"\n- \"Show me my top 5 holdings by value\"\n- \"Do I already own HIMS, and what's my current position?\"\n- \"List my Robinhood accounts, then show positions for my IRA account.\"\n- \"Get me a quote for AAPL\"\n\nFor single-symbol portfolio questions, prefer `robinhood_get_position` over\n`robinhood_get_positions`. The single-symbol tool avoids rebuilding every\nholding and is much faster for questions like \"Should I add more HIMS?\"\n\n**Analysis requests:**\n\n- \"Compare the fundamentals of GOOGL vs META\"\n- \"Which of my stocks are trading below their 52-week average?\"\n- \"Show me the price chart for TSLA over the past year\"\n- \"What's my best performing stock? What's my worst?\"\n\n**Research workflows:**\n\n- \"I want to understand the cruise line industry. Pull data on CCL, RCL, and NCLH - compare their fundamentals and recent performance.\"\n- \"Find stocks in my portfolio with a P/E under 15 and positive earnings growth\"\n- \"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.\"\n\n## Limitations\n\n- **Read-only**: Cannot place trades, modify watchlists, or change account settings\n- **Unofficial API**: Robinhood may change their API at any time, breaking functionality\n- **No real-time streaming**: Quotes are point-in-time, not live feeds\n- **Session expiry**: You may need to re-authenticate periodically\n- **Rate limits**: Heavy usage may trigger Robinhood's rate limiting\n\n## Security Notes\n\n- Credentials are only used locally to authenticate with Robinhood\n- Session tokens are cached in `~/.tokens/robinhood.pickle` by robin_stocks\n- Never commit your `.env` file or expose credentials\n- This tool cannot execute trades - it's read-only by design\n\n## Development\n\n```bash\ngit clone https://github.com/verygoodplugins/robinhood-mcp.git\ncd robinhood-mcp\npip install -e \".[dev]\"\n\n# Lint\nruff check . && ruff format --check .\n\n# Test\npytest\n\n# Run locally\nrobinhood-mcp\n```\n\n## Troubleshooting\n\n**\"Not logged in\" errors:**\n\n- Verify your username and password are correct\n- If you have 2FA with an authenticator app, you need `ROBINHOOD_TOTP_SECRET`\n- Try logging in through the Robinhood app to ensure your account isn't locked\n- **Tool calls hang briefly then fail with \"Login returned empty result\":** no\n cached session and no `ROBINHOOD_TOTP_SECRET`, so the server is waiting for\n you to approve a push notification in the Robinhood mobile app. Tap\n \"Approve\" within `ROBINHOOD_APPROVAL_TIMEOUT` seconds (default 60) and call\n the tool again — the session pickle is now cached and subsequent calls won't\n prompt. If TOTP is available on your account, adding `ROBINHOOD_TOTP_SECRET`\n removes the prompt entirely. After a failure the server caches the error for\n ~5 min; restart Claude Desktop to retry sooner.\n\n**\"Non-base32 digit found\" error:**\n\n- Your TOTP secret contains invalid characters\n- The secret should only contain letters A-Z and digits 2-7\n- If you don't use an authenticator app, remove `ROBINHOOD_TOTP_SECRET` entirely\n\n**Rate limiting:**\n\n- robin_stocks doesn't have built-in rate limiting\n- If you hit rate limits, wait a few minutes before retrying\n\n## License\n\nMIT\n\n## Disclaimer\n\nThis 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.\n\n**This project is not affiliated with, endorsed by, or connected to Robinhood Markets, Inc.**\n\n## Automation Examples\n\n### Daily Portfolio Review with Claude Code\n\nSet up a cron job to get a daily portfolio briefing:\n\n```bash\n# ~/.claude/commands/portfolio-review.md\n---\ndescription: \"Daily portfolio health check\"\n---\nUsing the robinhood MCP tools:\n1. Get my current portfolio value and day change\n2. Identify my top 3 gainers and top 3 losers today\n3. Flag any positions that are down more than 20% from cost basis\n4. Check if any holdings have earnings in the next 7 days\n5. Give me a 2-3 sentence summary I can read with my morning coffee\n```\n\nRun it daily:\n\n```bash\n# Add to crontab -e\n0 7 * * 1-5 cd ~/Projects && claude -p \"/portfolio-review\" --dangerously-skip-permissions >> ~/portfolio-reports/$(date +\\%Y-\\%m-\\%d).md\n```\n\n### Weekly Research Digest\n\n```bash\n# ~/.claude/commands/weekly-research.md\n---\ndescription: \"Weekly deep dive on portfolio\"\n---\nFor each of my top 10 holdings by value:\n1. Pull current fundamentals and compare to sector averages\n2. Get recent news and analyst rating changes\n3. Flag any significant changes from last week\n4. Identify 2-3 stocks from my watchlist that might be worth adding\n\nFormat as a markdown report I can review on the weekend.\n```\n\n## Credits\n\nBuilt with 🧡 by [Jack Arturo](https://drunk.support) at [Very Good Plugins](https://verygoodplugins.com/?utm_source=robinhood-mcp).\n\nPowered by [robin_stocks](https://github.com/jmfernandes/robin_stocks) and [FastMCP](https://github.com/jlowin/fastmcp).\n\n## Links\n\n- [GitHub](https://github.com/verygoodplugins/robinhood-mcp)\n- [PyPI](https://pypi.org/project/robinhood-mcp/)\n- [Very Good Plugins](https://verygoodplugins.com/?utm_source=robinhood-mcp)\n- [AutoMem](https://automem.ai) - AI memory infrastructure\n- [robin_stocks Documentation](https://robin-stocks.readthedocs.io/)\n- [Model Context Protocol](https://modelcontextprotocol.io/)\n",
"bytes": 13234,
"sha": "3be36b7b071a0217acc3603fe4e6d7dd098aabc47af5bddb9feff9d315ae82ad",
"repo_slug": "verygoodplugins/robinhood-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_verygoodplugins_robinhood_mcp_974dddd9/readme"
}