内容
# E*TRADE MCP 服务器
用于 E*TRADE API 的模型上下文协议（MCP）服务器，使像 Claude 这样的 LLM 能够检索股票和期权市场数据。
## 功能特点
- **OAuth 1.0 身份验证** - 安全、持久的令牌存储，自动生命周期管理
- **股票行情** - 实时和延迟的股票行情，可选的盈利日期
- **批量行情** - 单次请求最多可获取 25 支股票的行情
- **期权链** - 完整的期权链数据，包括执行价、到期日、希腊字母和买卖价
- **期权行情** - 特定期权合约的详细行情
- **自动重试** - 内置重试逻辑，用于处理 API 速率限制和令牌激活
- **MCP 集成** - 与 Claude Desktop 和其他 MCP 客户端无缝集成
## 先决条件
- Python 3.10 或更高版本
- E*TRADE 账户
- E*TRADE API 凭证（[在此处获取](https://developer.etrade.com)）
- `uv` 包管理器（[在此处安装](https://github.com/astral-sh/uv)）
## 安装
### 1. 安装 uv（如果尚未安装）
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### 2. 克隆和设置项目
```bash
cd etrade-mcp
# 创建虚拟环境
uv venv
# 激活虚拟环境
# 在 Windows 上：
.venv\Scripts\activate
# 在 macOS/Linux 上：
source .venv/bin/activate
# 安装依赖项
uv pip install -e .
```
### 3. 配置环境
在项目根目录中创建一个 `.env` 文件：
```bash
# 复制示例文件
cp .env.example .env
# 使用您的凭证编辑 .env
```
**.env 文件：**
```env
ETRADE_CONSUMER_KEY=您的消费者密钥
ETRADE_CONSUMER_SECRET=您的消费者密钥
ETRADE_ENVIRONMENT=sandbox # 使用“production”进行实时交易
```
**重要：**
- 首先使用 `sandbox` 环境进行测试
- 只有经过彻底测试后才切换到 `production`
- 生产环境需要实时 E*TRADE 经纪账户
## OAuth 设置
OAuth 身份验证通过 MCP 服务器自动处理。您第一次使用 Claude 的服务器时，系统将提示您授权：
1. Claude 将调用 `setup_oauth` 工具（最初不需要验证码）
2. 您的浏览器将打开到 E*TRADE 授权页面
3. 授权后，E*TRADE 将显示一个 5 个字符的验证码
4. 将验证码提供给 Claude，Claude 将再次调用 `setup_oauth`
5. 令牌已加密存储在本地，并自动续期
或者，您可以运行独立的 OAuth 设置：
```bash
python -m server.auth.setup
```
## 运行测试
```bash
# 安装开发依赖项
uv pip install -e ".[dev]"
# 运行所有测试
pytest
# 运行覆盖率测试
pytest --cov=server tests/
# 运行特定的测试文件
pytest tests/test_token_store.py -v
```
## Claude Desktop 配置
**macOS：** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows：** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"etrade": {
"command": "python",
"args": [
"-m",
"server.main"
],
"cwd": "/absolute/path/to/etrade-mcp",
"env": {
"ETRADE_CONSUMER_KEY": "您的消费者密钥",
"ETRADE_CONSUMER_SECRET": "您的消费者密钥",
"ETRADE_ENVIRONMENT": "sandbox"
}
}
}
}
```
替换 `/absolute/path/to/etrade-mcp` 为您的实际项目路径，并添加您的凭证。
## 与 Claude 一起使用
配置完成后，Claude 可以通过自然语言访问 E*TRADE 数据：
**股票行情：**
- “苹果股票的当前价格是多少？”
- “获取 AAPL、MSFT 和 GOOGL 的行情，附带盈利日期”
- “显示 TSLA 的价格和交易量”
**期权数据：**
- “显示 2025 年 1 月份到期特斯拉的期权链”
- “AAPL 行权价 180 美元的期权希腊字母是多少？”
- “获取 SPY 每周期权在 450 美元附近的买卖价差”
- “显示 NVDA 下个月到期的看跌期权”
## 可用工具
### 身份验证
**`setup_oauth`** - OAuth 1.0 身份验证流程
- 步骤 1：调用时不带 `verification_code` 获取授权 URL
- 步骤 2：调用时带 `verification_code`（来自 E*TRADE 的 5 个字符）完成身份验证
- 令牌自动存储和管理
### 股票行情
**`get_stock_quote`** - 获取单个股票的行情
- 输入：`symbol`（例如，“AAPL”），可选 `include_earnings`（默认值：false）
- 返回：价格、交易量、买卖价、涨跌幅，以及可选的下一次盈利日期
**`get_batch_quotes`** - 获取多个股票的行情
- 输入：`symbols`（数组，最多 25 个），可选 `include_earnings`（默认值：false）
- 返回：所有请求符号的行情
### 期权数据
**`get_option_chains`** - 获取期权链数据
- 输入：`symbol`，可选过滤器：
- `expiry_year`、`expiry_month`、`expiry_day` - 按到期日期过滤
- `chain_type` - “CALL”、“PUT” 或 “CALLPUT”（默认值）
- `strike_price_near` - 获取特定价格附近的行权价
- `no_of_strikes` - 限制返回的行权价数量
- `include_weekly` - 包括每周期权（默认值：false）
- `skip_adjusted` - 跳过调整后的期权（默认值：true）
- `option_category` - “STANDARD”（默认值）、“ALL” 或 “MINI”
- `price_type` - “ATNM”（按市值计价，默认值）或 “ALL”
- 返回：可用的行权价、到期日期、买卖价、希腊字母、开仓兴趣和交易量
**`get_option_quote`** - 获取特定的期权行情
- 输入：`option_symbols`（OSI 格式符号数组，最多 25 个）
- 返回：详细的期权行情数据，包括希腊字母和理论值
## 项目结构
```
etrade-mcp/
├── server/
│ ├── auth/
│ │ ├── oauth_manager.py # OAuth 会话和令牌生命周期
│ │ ├── token_store.py # 加密令牌存储
│ │ └── setup.py # 独立 OAuth 设置
│ ├── tools/
│ │ ├── oauth_tools.py # MCP OAuth 工具
│ │ ├── stock_quotes.py # 股票行情工具
│ │ └── options_quotes.py # 期权链和行情工具
│ ├── utils/
│ │ └── retry.py # 自动重试逻辑
│ ├── config.py # 配置管理
│ └── main.py # MCP 服务器入口点
├── tests/
│ ├── test_token_store.py # 令牌存储测试
│ └── test_auth.py # OAuth 管理器测试
├── .env.example # 示例环境配置
├── pyproject.toml # 项目元数据和依赖项
└── README.md
```
## 开发状态
**✅ v0.1.0 - 所有核心功能已完成**
### 基础
- [x] 使用现代工具（uv、pyproject.toml）设置项目
- [x] 基于环境的配置管理
- [x] 加密令牌存储和生命周期管理
- [x] OAuth 1.0 身份验证流程
- [x] 身份验证组件的单元测试
### 股市数据
- [x] 支持盈利的单个股票行情工具
- [x] 批量行情（最多 25 个符号）
- [x] 实时和延迟行情处理
### 期权数据
- [x] 具有综合过滤的期权链
- [x] 按 OSI 符号获取期权行情
- [x] 希腊字母、理论值和开仓利息
- [x] 支持标准、每周和迷你期权
### MCP 集成
- [x] 通过 MCP 工具进行两步 OAuth 流程
- [x] API 速率限制的自动重试逻辑
- [x] 令牌激活延迟处理
- [x] 与 Claude Desktop 完全集成
### 质量和可靠性
- [x] 全面的错误处理
- [x] 调试日志记录到文件和 stderr
- [x] 自动令牌续期
- [x] 为 E*TRADE 实时账户做好生产准备
## 安全说明
- **请勿提交 `.env` 文件** - 包含敏感凭证
- **令牌已加密** - 存储在 `.etrade_tokens.enc` 中
- **首先使用 sandbox** - 在生产之前进行彻底测试
- **密钥的环境变量** - 在生产中设置 `ETRADE_TOKEN_KEY`
## 故障排除
### OAuth 设置失败
- 验证消费者密钥和密钥是否正确
- 检查您是否使用正确的环境（sandbox/production）
- 确保您的 E*TRADE 账户具有 API 访问权限
### “未找到令牌”错误
- 运行 `python -m server.auth.setup` 进行身份验证
- 检查 `.etrade_tokens.enc` 文件是否存在
- 验证 `ETRADE_TOKEN_KEY` 是否一致
### 导入错误
- 确保虚拟环境已激活
- 运行 `uv pip install -e .` 安装依赖项
## 最近的改进
### 令牌生命周期管理（最新）
- 到期时的自动令牌续期
- 令牌激活延迟的优雅处理
- 跨重启的持久会话状态
### 增强的期权支持
- 完整的 E*TRADE API 规范合规性
- 支持每周和迷你期权
- 按到期日期和执行价格进行灵活过滤
- 完整的希腊字母和理论定价数据
### 可靠性增强
- API 速率限制的自动重试逻辑
- 令牌激活的指数退避
- 全面的错误处理和日志记录
- 使用实时 E*TRADE 账户进行生产测试
## 资源
- [E*TRADE API 文档](https://developer.etrade.com)
- [模型上下文协议](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
## 许可证
MIT
## 贡献
欢迎贡献！请：
1. 遵循测试驱动开发
2. 为新功能添加测试
3. 更新文档
4. 首先在 sandbox 环境中测试
