README.md•5 kB
# 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