Robinhood MCP Server - User Guide

Overview

The Robinhood MCP Server provides a comprehensive interface to the Robinhood Crypto API. This server handles authentication, account management, market data retrieval, and trading operations through both REST API and WebSocket interfaces.

Table of Contents

• Features
• Prerequisites
• Installation
• Configuration
• Running the Server
• API Documentation
• Testing
• Development
• Security
• Troubleshooting
• License
• Disclaimer

Features

• REST API for account management and trading operations
• WebSocket support for real-time market data and order updates
• Comprehensive error handling and logging
• Rate limiting and security best practices
• Easy configuration via environment variables

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)
• Robinhood API credentials

Installation

1. Clone the repository:

   git clone https://github.com/rohitsingh-iitd/robinhood-mcp-server
   cd robinhood-mcp-server
   

2. Set up a virtual environment (recommended):

   # Create a virtual environment
   python -m venv venv
   
   # Activate the virtual environment
   # On macOS/Linux:
   source venv/bin/activate
   # On Windows:
   # .\venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

Configuration

1. Create a .env file in the project root with the following content:

   # Required
   ROBINHOOD_API_KEY=your_api_key_here
   ROBINHOOD_PRIVATE_KEY=your_base64_encoded_private_key_here
   
   # Optional (with defaults)
   HOST=0.0.0.0
   PORT=8000
   WEBSOCKET_PORT=8001
   DEBUG=False
   LOG_LEVEL=INFO
   LOG_FILE=robinhood_mcp_server.log
   RATE_LIMIT_ENABLED=True
   RATE_LIMIT_REQUESTS=100
   RATE_LIMIT_PERIOD=60
   

2. Replace the placeholder values with your actual Robinhood API credentials.

Running the Server

Start the server with the following command:

python -m src.main

This will start:

• REST API server at http://localhost:8000
• WebSocket server at ws://localhost:8001

Running in Production

For production use, consider using a production-grade ASGI server like Uvicorn with Gunicorn:

pip install gunicorn uvicorn[standard]
gunicorn src.main:app --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Running the Server

Start the server with the following command:

python -m src.main

This will start both the REST API server (default port 8000) and the WebSocket server (default port 8001).

REST API Endpoints

Authentication

• GET /auth/status - Check authentication status

Account

• GET /account - Get account information
• GET /account/holdings - Get account holdings (optional query param: asset_code)

Market Data

• GET /market/best-price - Get best bid/ask price (optional query param: symbol)
• GET /market/estimated-price - Get estimated price for quantity (required query params: symbol, side, quantity)

Trading

• GET /trading/pairs - Get available trading pairs (optional query param: symbol)
• GET /trading/orders - Get order history (optional query param: status)
• GET /trading/orders/{id} - Get order details
• POST /trading/orders - Place a new order
  • Required fields: symbol, side, quantity
  • Optional fields: type, price, time_in_force, stop_price
• DELETE /trading/orders/{id} - Cancel an order

WebSocket API

The WebSocket server provides real-time updates for market data and order status.

Connection

Connect to the WebSocket server at:

ws://localhost:8001

Market Data Subscription

Subscribe to market data updates:

{
  "type": "market_data",
  "action": "subscribe",
  "symbols": ["BTC-USD", "ETH-USD"]
}

Unsubscribe from market data updates:

{
  "type": "market_data",
  "action": "unsubscribe",
  "symbols": ["BTC-USD", "ETH-USD"]
}

Order Updates Subscription

Subscribe to order updates:

{
  "type": "orders",
  "action": "subscribe"
}

Unsubscribe from order updates:

{
  "type": "orders",
  "action": "unsubscribe"
}

Ping/Pong

Send a ping to keep the connection alive:

{
  "type": "ping"
}

The server will respond with:

{
  "type": "pong"
}

Testing

Run the validation tests to ensure the server is working correctly:

python -m tests.test_server

Configuration Options

The following environment variables can be configured in the .env file:

• ROBINHOOD_API_KEY - Your Robinhood API key
• ROBINHOOD_PRIVATE_KEY - Your base64-encoded private key
• HOST - Server host (default: 0.0.0.0)
• PORT - REST API server port (default: 8000)
• DEBUG - Enable debug mode (default: False)
• LOG_LEVEL - Logging level (default: INFO)
• LOG_FILE - Log file path (default: robinhood_mcp_server.log)
• RATE_LIMIT_ENABLED - Enable rate limiting (default: True)
• RATE_LIMIT_REQUESTS - Maximum requests per period (default: 100)
• RATE_LIMIT_PERIOD - Rate limit period in seconds (default: 60)

Security Considerations

• API keys and secrets are stored in environment variables, never in code
• All sensitive data is properly handled
• Input validation is implemented for all API endpoints
• Rate limiting is enforced to prevent abuse
• Proper error handling to avoid leaking sensitive information

Troubleshooting

If you encounter issues:

1. Check the log file for detailed error messages
2. Verify your API credentials are correct
3. Ensure you have proper network connectivity
4. Check that the Robinhood API is available

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

The author is not responsible for any loss or damage that may occur as a result of using this project.