robinhood-mcp CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code when working with this repository.

Project Overview

robinhood-mcp is a read-only MCP server that wraps the robin_stocks Python library to provide research tools for Robinhood portfolio data. This is strictly a research/educational tool - no trading functionality is exposed.

Architecture

src/robinhood_mcp/
├── __init__.py      # Package version
├── auth.py          # Authentication with TOTP support
├── tools.py         # 12 read-only tool implementations
└── server.py        # FastMCP server with tool registration

Key Design Decisions

1. Read-Only Only: We explicitly do NOT expose any trading functions:

   • No order_buy_*, order_sell_*
   • No cancel_*_order
   • No account modification functions

2. FastMCP: Uses FastMCP for simpler decorator-based tool registration

3. Lazy Authentication: Login happens on first tool call, not server startup

4. Error Handling: All robin_stocks calls are wrapped with _safe_call() for consistent error handling

Common Commands

# Install dependencies
pip install -e ".[dev]"

# Run linting
ruff check .
ruff format --check .

# Run tests
pytest -v

# Run with coverage
pytest --cov=src --cov-report=html

# Run the server
robinhood-mcp

Environment Variables

Variable	Required	Description
ROBINHOOD_USERNAME	Yes	Robinhood account email
ROBINHOOD_PASSWORD	Yes	Robinhood account password
ROBINHOOD_TOTP_SECRET	No	Base32 TOTP secret for 2FA

Testing

Tests use mocked robin_stocks responses. To run with real credentials (careful!):

# Set env vars first
pytest tests/ -v

Adding New Tools

1. Add the implementation to tools.py with proper type hints
2. Register in server.py with @mcp.tool() decorator
3. Add tests in tests/test_tools.py
4. Update server.json tool list
5. Update README.md tool table

Publishing

This project uses GitHub Actions for CI/CD: