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) ```bash uvx --from git+https://github.com/davdunc/mcp_etrade.git mcp_etrade ``` ### Install via pip ```bash pip install git+https://github.com/davdunc/mcp_etrade.git ``` ### Development Install ```bash git clone https://github.com/davdunc/mcp_etrade.git cd mcp_etrade pip install -e . ``` ## Configuration Set your E*TRADE API credentials: ```bash export ETRADE_OAUTH_CONSUMER_KEY="your_consumer_key" export ETRADE_OAUTH_CONSUMER_SECRET="your_consumer_secret" ``` ## Usage ### Standalone Server ```bash python -m mcp_etrade.server ``` ### With Colosseum Framework Add to `~/.config/colosseum/mcp.json`: ```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: ```python # 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: ```bash 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