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

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