内容
# 思科瑞姆 MCP
一个用于期权交易研究的Python MCP服务器，基于**查尔斯·施瓦布交易员 API**（前身为thinkorswim/TD Ameritrade）。设计用于与克劳德代码和AI代理集成，可选的FastAPI侧车用于后端集成。
## 功能
- **实时行情和价格历史**，通过施瓦布REST API
- **包含完整希腊字母的期权链** - delta, gamma, theta, vega, IV, OI, volume
- **IV分析** - IV排名，IV百分位，预计变动
- **多腿策略构建器** - 垂直价差，铁鹰，时间价差；净希腊字母，盈亏平衡点，最大利润/损失
- **声明式扫描器** - 按IV排名，价格等筛选；内置模板
- **速率限制感知客户端** - 110 req/min令牌桶，429回退
- **FastAPI侧车**（第4阶段）用于NestJS/后端集成
- **ToS桌面自动化存根**（第3阶段）用于thinkscript扫描，通过pyautogui和CSV导出
## 先决条件
- Python 3.11+
- [`uv`](https://docs.astral.sh/uv/)（推荐）或pip
- [查尔斯·施瓦布证券账户](https://www.schwab.com/)（API访问所需）
- 在[developer.schwab.com](https://developer.schwab.com)注册的应用 → **交易员 API（个人）**
> **注意：** API审批需要1-3个工作日。在开始前申请。
## 设置
```bash
# 1. 安装依赖
uv sync --all-extras
# 2. 配置凭证
cp .env.example .env
# 编辑.env文件，填写SCHWAB_API_KEY和SCHWAB_APP_SECRET
# 3. 运行OAuth流程（一次性，打开浏览器）
make auth
# 4. 验证令牌有效
make smoke
```
## 用法
### 运行MCP服务器（stdio - 用于克劳德代码/IDE代理）
```bash
make serve-mcp
```
添加到克劳德代码配置（`~/.claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"thinkorswim": {
"command": "uv",
"args": ["run", "python", "-m", "tos_mcp.server"],
"cwd": "/path/to/thinkorswim_mcp"
}
}
}
```
### 运行FastAPI侧车（用于后端集成）
```bash
make serve-api # http://localhost:8181
```
### 运行测试
```bash
make test
```
## MCP工具
| 工具 | 描述 |
|------|-------------|
| `get_quote` | 一个或多个符号的实时行情 |
| `get_price_history` | OHLCV条形图（日/周/分钟） |
| `get_option_chain` | 完整的希腊字母、IV、OI、交易量链 |
| `get_iv_rank` | IV排名（0-100）vs 过去一年 |
| `get_iv_percentile` | 过去一年中IV较低的百分比 |
| `get_expected_move` | ±1σ范围到给定到期日期 |
| `build_options_strategy` | 多腿策略的净希腊字母 + 盈亏平衡点 |
| `screen_list_scans` | 列出可用的扫描模板 |
| `screen_run_scan` | 在一个宇宙中执行扫描 |
| `screen_save_scan` | 保存自定义扫描规范 |
| `request_tos_scan` | 通过ToS桌面触发thinkscript扫描（第3阶段） |
## 项目结构
```
thinkorswim_mcp/
├── tos_core/ # 可导入的业务逻辑（无MCP/HTTP）
│ ├── auth.py # OAuth +令牌存储（schwab-py）
│ ├── client.py # 速率限制的施瓦布REST包装器
│ ├── chains.py # 期权链获取 + 希腊字母归一化
│ ├── analytics.py # IV排名，预计移动，策略构建器
│ └── screener/ # 声明式扫描引擎 + 规范模式
├── tos_mcp/ # FastMCP服务器（薄处理程序 → tos_core）
├── tos_api/ # FastAPI侧车用于后端集成
├── tos_export_worker/ # pyautogui ToS桌面工作线程（第3阶段存根）
└── tests/
```
`tos_core` 可独立导入 - MCP服务器和FastAPI侧车都委托给它。这使得业务逻辑可测试，并在任何传输层之外可重用。
## 环境变量
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `SCHWAB_API_KEY` | — | developer.schwab.com上的应用密钥 |
| `SCHWAB_APP_SECRET` | — | developer.schwab.com上的应用密钥 |
| `SCHWAB_CALLBACK_URL` | `https://127.0.0.1` | OAuth回调（必须与注册的URL匹配） |
| `SCHWAB_TOKEN_PATH` | `~/.tos/schwab_token.json` | OAuth令牌存储位置 |
| `TOS_EXPORT_DIR` | `~/.tos/exports` | ToS CSV导出文件夹（第3阶段） |
## 限制
- **实时交易** - 施瓦布没有API的沙盒或模拟交易环境
- **速率限制** - 120请求/分钟；客户端强制执行110请求/分钟，自动回退
- **thinkscript** - 无法通过任何API运行；ToS自动化模块（第3阶段）是使用桌面GUI自动化作为最佳努力的变通方法
- **只读** - 不公开订单放置
## 许可证
MIT
