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)

2. Clone and Setup Project

3. Configure Environment

Create a .env file in the project root:

.env file:

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:

Running Tests

Claude Desktop Configuration

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

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

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 - 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