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)
uvpackage 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
sandboxenvironment for testing - Switch to
productiononly 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:
- Claude will call the
setup_oauthtool (no verification code needed initially) - Your browser will open to the E*TRADE authorization page
- After authorizing, E*TRADE will display a 5-character verification code
- Provide the code to Claude, who will call
setup_oauthagain with the code - 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_codeto 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"), optionalinclude_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), optionalinclude_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 datechain_type- "CALL", "PUT", or "CALLPUT" (default)strike_price_near- Get strikes near a specific priceno_of_strikes- Limit number of strikes returnedinclude_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
- Project setup with modern tooling (uv, pyproject.toml)
- Environment-based configuration management
- Encrypted token storage with lifecycle management
- OAuth 1.0 authentication flow
- Unit tests for auth components
Stock Market Data
- Single stock quote tool with earnings support
- Batch quotes (up to 25 symbols)
- Real-time and delayed quote handling
Options Data
- Options chains with comprehensive filtering
- Options quotes by OSI symbol
- Greeks, theoretical values, and open interest
- Support for standard, weekly, and mini options
MCP Integration
- Two-step OAuth flow via MCP tools
- Automatic retry logic for API rate limits
- Token activation delay handling
- Full integration with Claude Desktop
Quality & Reliability
- Comprehensive error handling
- Debug logging to file and stderr
- Automatic token renewal
- Production-ready for E*TRADE live accounts
Security Notes
- Never commit
.envfile - 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_KEYin 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.setupto authenticate - Check
.etrade_tokens.encfile exists - Verify
ETRADE_TOKEN_KEYis 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
License
MIT
Contributing
Contributions welcome! Please:
- Follow test-driven development
- Add tests for new features
- Update documentation
- Test with sandbox environment first