E*TRADE MCP Server

Model Context Protocol (MCP) server for E*TRADE API, enabling LLMs like Claude to retrieve stock and options market data.

Features

• OAuth 1.0 Authentication - Secure, persistent token storage with automatic lifecycle management
• Stock Quotes - Real-time and delayed stock quotes with optional earnings dates
• Batch Quotes - Retrieve up to 25 stock quotes in a single request
• Options Chains - Full options chain data with strikes, expirations, Greeks, and bid/ask
• Options Quotes - Detailed quotes for specific option contracts
• Automatic Retries - Built-in retry logic for handling API rate limits and token activation
• MCP Integration - Seamless integration with Claude Desktop and other MCP clients

Prerequisites

• Python 3.10 or higher
• E*TRADE account
• E*TRADE API credentials (Get them here)
• uv package manager (Install here)

Installation

1. Install uv (if not already installed)

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone and Setup Project

cd etrade-mcp

# Create virtual environment
uv venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
uv pip install -e .

3. Configure Environment

Create a .env file in the project root:

# Copy example file
cp .env.example .env

# Edit .env with your credentials

.env file:

ETRADE_CONSUMER_KEY=your_consumer_key_here
ETRADE_CONSUMER_SECRET=your_consumer_secret_here
ETRADE_ENVIRONMENT=sandbox  # Use 'production' for live trading

Important:

• Start with sandbox environment for testing
• Switch to production only after thorough testing
• Production requires live E*TRADE brokerage account

OAuth Setup

OAuth authentication is handled automatically through the MCP server. When you first use the server with Claude, you'll be prompted to authorize:

1. Claude will call the setup_oauth tool (no verification code needed initially)
2. Your browser will open to the E*TRADE authorization page
3. After authorizing, E*TRADE will display a 5-character verification code
4. Provide the code to Claude, who will call setup_oauth again with the code
5. Tokens are saved encrypted locally and automatically renewed

Alternatively, you can run the standalone OAuth setup:

python -m server.auth.setup

Running Tests

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

# Run all tests
pytest

# Run with coverage
pytest --cov=server tests/

# Run specific test file
pytest tests/test_token_store.py -v

Claude Desktop Configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "etrade": {
      "command": "python",
      "args": [
        "-m",
        "server.main"
      ],
      "cwd": "/absolute/path/to/etrade-mcp",
      "env": {
        "ETRADE_CONSUMER_KEY": "your_consumer_key",
        "ETRADE_CONSUMER_SECRET": "your_consumer_secret",
        "ETRADE_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Replace /absolute/path/to/etrade-mcp with your actual project path and add your credentials.

Usage with Claude

Once configured, Claude can access E*TRADE data through natural language:

Stock Quotes:

• "What's the current price of Apple stock?"
• "Get quotes for AAPL, MSFT, and GOOGL with earnings dates"
• "Show me the price and volume for TSLA"

Options Data:

• "Show me the option chain for Tesla expiring in January 2025"
• "What are the Greeks for AAPL calls at $180 strike?"
• "Get the bid/ask spread for SPY weekly options near $450"
• "Show me put options for NVDA expiring next month"

Available Tools

Authentication

setup_oauth - OAuth 1.0 authentication flow

• Step 1: Call without verification_code to get authorization URL
• Step 2: Call with verification_code (5 characters from E*TRADE) to complete auth
• Tokens are automatically stored and managed

Stock Quotes

get_stock_quote - Get quote for a single stock

• Input: symbol (e.g., "AAPL"), optional include_earnings (default: false)
• Returns: Price, volume, bid/ask, change, and optionally next earnings date

get_batch_quotes - Get quotes for multiple stocks

• Input: symbols (array, up to 25), optional include_earnings (default: false)
• Returns: Quotes for all requested symbols

Options Data

get_option_chains - Get options chain data

• Input: symbol, optional filters:
  • expiry_year, expiry_month, expiry_day - Filter by expiration date
  • chain_type - "CALL", "PUT", or "CALLPUT" (default)
  • strike_price_near - Get strikes near a specific price
  • no_of_strikes - Limit number of strikes returned
  • include_weekly - Include weekly options (default: false)
  • skip_adjusted - Skip adjusted options (default: true)
  • option_category - "STANDARD" (default), "ALL", or "MINI"
  • price_type - "ATNM" (at-the-money, default) or "ALL"
• Returns: Available strikes, expirations, bid/ask, Greeks, open interest, volume

get_option_quote - Get specific option quotes

• Input: option_symbols (array of OSI format symbols, up to 25)
• Returns: Detailed option quote data including Greeks and theoretical values

Project Structure

etrade-mcp/
├── server/
│   ├── auth/
│   │   ├── oauth_manager.py    # OAuth session & token lifecycle
│   │   ├── token_store.py      # Encrypted token storage
│   │   └── setup.py            # Standalone OAuth setup
│   ├── tools/
│   │   ├── oauth_tools.py      # MCP OAuth tool
│   │   ├── stock_quotes.py     # Stock quote tools
│   │   └── options_quotes.py   # Options chain & quote tools
│   ├── utils/
│   │   └── retry.py            # Automatic retry logic
│   ├── config.py               # Configuration management
│   └── main.py                 # MCP server entry point
├── tests/
│   ├── test_token_store.py     # Token storage tests
│   └── test_auth.py            # OAuth manager tests
├── .env.example                # Example environment config
├── pyproject.toml              # Project metadata & dependencies
└── README.md

Development Status

✅ v0.1.0 - All Core Features Complete

Foundation

• [x] Project setup with modern tooling (uv, pyproject.toml)
• [x] Environment-based configuration management
• [x] Encrypted token storage with lifecycle management
• [x] OAuth 1.0 authentication flow
• [x] Unit tests for auth components

Stock Market Data

• [x] Single stock quote tool with earnings support
• [x] Batch quotes (up to 25 symbols)
• [x] Real-time and delayed quote handling

Options Data

• [x] Options chains with comprehensive filtering
• [x] Options quotes by OSI symbol
• [x] Greeks, theoretical values, and open interest
• [x] Support for standard, weekly, and mini options

MCP Integration

• [x] Two-step OAuth flow via MCP tools
• [x] Automatic retry logic for API rate limits
• [x] Token activation delay handling
• [x] Full integration with Claude Desktop

Quality & Reliability

• [x] Comprehensive error handling
• [x] Debug logging to file and stderr
• [x] Automatic token renewal
• [x] Production-ready for E*TRADE live accounts

Security Notes

• Never commit .env file - Contains sensitive credentials
• Tokens are encrypted - Stored in .etrade_tokens.enc
• Use sandbox first - Test thoroughly before production
• Environment variable for key - Set ETRADE_TOKEN_KEY in production

Troubleshooting

OAuth Setup Fails

• Verify consumer key and secret are correct
• Check you're using the right environment (sandbox/production)
• Ensure your E*TRADE account has API access

"No tokens found" Error

• Run python -m server.auth.setup to authenticate
• Check .etrade_tokens.enc file exists
• Verify ETRADE_TOKEN_KEY is consistent

Import Errors

• Ensure virtual environment is activated
• Run uv pip install -e . to install dependencies

Recent Improvements

Token Lifecycle Management (Latest)

• Automatic token renewal on expiration
• Graceful handling of token activation delays
• Persistent session state across restarts

Enhanced Options Support

• Full E*TRADE API spec compliance
• Support for weekly and mini options
• Flexible filtering by expiration and strike price
• Complete Greeks and theoretical pricing data

Reliability Enhancements

• Automatic retry logic for API rate limits
• Exponential backoff for token activation
• Comprehensive error handling and logging
• Production-tested with live E*TRADE accounts

Resources

• E*TRADE API Documentation
• Model Context Protocol
• MCP Python SDK

License

MIT

Contributing

Contributions welcome! Please:

1. Follow test-driven development
2. Add tests for new features
3. Update documentation
4. Test with sandbox environment first