davdunc/mcp_etrade

E*TRADE MCP Server

A comprehensive Model Context Protocol (MCP) server for E*TRADE integration with OAuth authentication, account management, risk calculations, watch lists, and trading guardrails.

Features

🔐 OAuth Authentication

• Complete E*TRADE OAuth 1.0a flow
• Token management and renewal
• Secure credential handling

💰 Account Management

• Account balance retrieval
• Transaction history
• Portfolio viewing
• Real-time account data

📊 Risk Management

• R-multiple risk calculations
• Daily loss tracking
• Position sizing guardrails
• Risk validation before orders

📋 Watch Lists

• Create, read, update, delete watch lists
• Symbol management
• Independent from portfolio positions

📈 Market Data

• Option chains with expiration dates
• Real-time quotes
• Security lookup by company name

🚨 Alerts

• Price alerts management
• Alert notifications
• Custom alert conditions

Installation

Prerequisites

• Python 3.11+
• E*TRADE developer account with API keys

Install via UVX (Recommended)

uvx --from git+https://github.com/davdunc/mcp_etrade.git mcp_etrade

Install via pip

pip install git+https://github.com/davdunc/mcp_etrade.git

Development Install

git clone https://github.com/davdunc/mcp_etrade.git
cd mcp_etrade
pip install -e .

Configuration

Set your E*TRADE API credentials:

export ETRADE_OAUTH_CONSUMER_KEY="your_consumer_key"
export ETRADE_OAUTH_CONSUMER_SECRET="your_consumer_secret"

Usage

Standalone Server

python -m mcp_etrade.server

With Colosseum Framework

Add to ~/.config/colosseum/mcp.json:

{
  "etrade": {
    "type": "etrade",
    "command": "uvx",
    "args": ["--from", "git+https://github.com/davdunc/mcp_etrade.git", "mcp_etrade"],
    "env": {
      "ETRADE_OAUTH_CONSUMER_KEY": "${ETRADE_OAUTH_CONSUMER_KEY}",
      "ETRADE_OAUTH_CONSUMER_SECRET": "${ETRADE_OAUTH_CONSUMER_SECRET}"
    }
  }
}

Available Tools

Authentication

• get_request_token - Start OAuth flow
• get_authorization_url - Get user authorization URL
• get_access_token - Complete OAuth flow
• renew_access_token - Refresh tokens
• revoke_access_token - Revoke access

Account Management

• get_account_balance - Get account balance and details
• list_transactions - List account transactions
• get_transaction_details - Get specific transaction details
• view_portfolio - View portfolio positions

Risk Management

• calculate_risk_parameters - Calculate R-multiple risk parameters
• validate_order_risk - Validate order against risk limits
• get_daily_risk_status - Get current daily risk utilization
• record_actual_loss - Record actual trading losses

Watch Lists

• create_watch_list - Create new watch list
• get_watch_lists - Get all watch lists
• update_watch_list - Update existing watch list
• delete_watch_list - Delete watch list

Market Data

• get_option_chains - Get option chains for symbols
• get_option_expire_dates - Get option expiration dates
• get_quotes - Get real-time quotes
• lookup_product - Search securities by company name

Alerts

• list_alerts - List price alerts
• delete_alerts - Delete alerts
• get_alert_details - Get alert details

Risk Management

The server includes comprehensive risk management features:

• Daily Risk Limits: Configurable percentage of account balance
• Position Size Limits: Maximum 50% of account per order
• Loss Tracking: Both potential and actual loss tracking
• Validation: Pre-order risk validation with detailed messages

Example risk validation:

# Validate order before placement
result = await call_tool("validate_order_risk", {
    "account_id": "your_account",
    "order_value": 1000.00,
    "risk_amount": 50.00,
    "risk_percentage": 1.0
})

Testing

Run the comprehensive test suite:

pytest

Test Coverage:

• 105 passing tests
• OAuth authentication flows
• Account management operations
• Risk calculation accuracy
• Watch list CRUD operations
• Market data retrieval
• Alert management

Architecture

• Clean JSON Output: Structured responses for agent consumption
• Comprehensive Error Handling: Graceful failure modes
• Mock Data Support: Full functionality without live API calls
• Modular Design: Separate concerns for OAuth, risk, data, etc.

Integration

Designed for integration with:

• Colosseum: Multi-agent trading framework
• LangChain: Agent tooling and orchestration
• MCP Clients: Any MCP-compatible system

License

GNU General Public License v3.0

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

Support

For issues and questions:

• GitHub Issues: https://github.com/davdunc/mcp_etrade/issues
• Documentation: See inline code documentation