Content
# 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](https://developer.etrade.com))
- `uv` package manager ([Install here](https://github.com/astral-sh/uv))
## Installation
### 1. Install uv (if not already installed)
```bash
# 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
```bash
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:
```bash
# Copy example file
cp .env.example .env
# Edit .env with your credentials
```
**.env file:**
```env
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:
```bash
python -m server.auth.setup
```
## Running Tests
```bash
# 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`
```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](https://developer.etrade.com)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/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
