Options ORB MCP System

一个演示优先的 MCP 服务器系统，向 LLM 客户端（Cursor / Claude Desktop）提供市场分析、研究、优化和执行工具。它交易由 开盘区间突破（ORB） 信号驱动的 限定风险期权垂直价差，按交易时段窗口（亚洲 / 伦敦 / 纽约）进行优化，并针对约 £1000 的资金设置严格的风险控制。

风险提示。 这是教育软件，不是金融建议。期权交易有损失本金的风险。系统默认使用模拟账户，除非你刻意拨动两个独立的安全开关，否则拒绝下达真实订单。“稳定回报”只是设计上的目标，绝非保证。

为什么设计成这个样子

• 你的需求描述了 ORB、交易时段窗口、SL/TP 和 MetaTrader。真实的期权（行权价/到期日/希腊字母）在 MT5 上并不存在，因此这里使用 Interactive Brokers（模拟 API + 英国访问权限 + 美国期权）。

• £1000 意味着只能做限定风险价差（垂直价差）。ORB 在标的资产上的突破是方向性信号；执行器负责下单价差。

• 针对美国期权重新定义了交易时段窗口：亚洲 = 隔夜 globex 区间，伦敦 = 欧盟/盘前，纽约 = 经典的美国开盘 ORB。

Related MCP server: IBKR TWS MCP Server

架构

LLM client (Cursor / Claude)
      |  MCP (stdio)
      +-- market-data-mcp   (ORB signal, regime, option chain, IV)
      +-- research-mcp      (trade journal, performance, learning)
      +-- optimiser-mcp     (backtest, walk-forward, compare strategies)
      +-- execution-mcp     (preview/place spreads with bracket SL/TP)
                 |
              core/ library  <----  dashboard/ (read-only web GUI, port 8787)
                 |
        IB Gateway / TWS  (paper first)

先决条件

1. Python 3.11+（已测试 3.13）。

2. 使用 pip 的虚拟环境（步骤见下文）。如果你有 uv，它也可作为可选的替代方案。

3. 启用模拟交易的 Interactive Brokers 账户，并运行启用了 API 的 TWS 或 IB Gateway（Configure -> API -> Settings -> “Enable ActiveX and Socket Clients”）。

   • 模拟默认值：TWS 7497，IB Gateway 4002。

   • 不熟悉？请按照分步 IBKR 设置指南 操作（安装 Gateway，登录模拟账户，启用 API，获取免费延迟数据）。

模拟交易默认使用 IBKR 实时数据；合成/“Demo data” 只是一个显式的离线开关。回测器和定价工具无需 IBKR 即可运行——只有实时市场数据和下单需要 Gateway/TWS 运行。模拟账户可获得免费的 15 分钟延迟数据；当你没有实时行情订阅时，系统会自动回退到该数据。

设置

在仓库根目录运行以下命令。这些命令假定你的虚拟环境已激活（因此 python/pytest 会解析到 .venv）。

# 1. Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate            # PowerShell / CMD
# source .venv/Scripts/activate   # Git Bash on Windows
# source .venv/bin/activate       # macOS / Linux

# 2. Install the project + dev tools (pytest, ruff)
pip install -e ".[dev]"

# 3. Configure
copy .env.example .env            # Windows;  Unix: cp .env.example .env
# then edit IBKR_PORT (IB Gateway paper = 4002, TWS paper = 7497)

# 4. Register the MCP servers with your client (writes .cursor/mcp.json)
python -m scripts.setup

# 5. Sanity check the tests (no IBKR needed)
pytest -q

# 6. Watch the whole loop run offline on synthetic data (no IBKR needed)
python -m scripts.demo

# 7. Open the GUI dashboard (historic trades, strategy used, live positions)
python -m dashboard.app           # then open http://127.0.0.1:8787

# (once IB Gateway is running) confirm the live connection + a sample quote
python -m scripts.check_ibkr

该演示端到端地演练每个智能体：它会发现一次 ORB 突破，对限定风险价差进行风险规模测算，模拟一次纸面成交，记录日志，然后回测、优化并对策略进行前向验证——全部离线完成。

uv sync --extra dev            # install
uv run orb-setup               # = python -m scripts.setup
uv run pytest -q               # = pytest -q
uv run python -m scripts.demo  # = python -m scripts.demo
uv run orb-dashboard           # = python -m dashboard.app
uv run python -m scripts.check_ibkr

orb-setup 和 orb-dashboard 是在 pyproject.toml 中定义的控制台脚本入口点；在 pip install -e . 之后，它们也会出现在你的 PATH 中。

仪表盘（GUI）

一个只读的 Web 仪表盘让你一目了然地查看所有内容：

python -m dashboard.app       # (uv: uv run orb-dashboard)
# open http://127.0.0.1:8787

它展示：

• 账户卡片 - 环境（PAPER/LIVE 徽章）、IBKR 连接、每日 P&L、每笔交易风险预算、未平仓头寸以及每日 kill-switch 状态。

• 权益曲线 - 从起始资金开始，已平仓交易的累计盈亏。

• 实时信号 - 每个交易时段窗口的当前 ORB 读数（带“Demo data”开关，因此无需 IBKR 也能工作）。

• 按窗口和按策略划分的绩效 - 胜率、期望值、盈利因子和总盈亏，让你了解哪些 ORB 窗口和哪些价差类型有效。

• 自动交易（播放按钮） - 一个启动/停止控件，自动运行 ORB 入场循环：每个时间间隔，它评估当前活跃的时段窗口，如果符合条件的突破通过所有风险门禁，就下一个按风险规模测算的价差（纸面或模拟）并记录日志。入场使用你选择的参数集（优化器排名、优化历史，或高级参数上的 使用这些参数进行交易）。在你做出选择之前，使用 windows.json 默认值。每个时段窗口最多进入 3 笔交易（亚洲 / 伦敦 / 纽约每天最多 9 笔），遵守每笔交易上限和每日 kill-switch，并显示实时活动日志。作为安全措施，对 LIVE 账户禁用——仅限纸面/模拟。

• 回测与模拟 - 选择标的、时段窗口和回看期，然后点击 运行回测 拉取历史数据（IBKR 实时历史数据，或离线演示数据），并模拟 ORB 价差策略。你会得到一条模拟权益曲线、完整指标（胜率、期望值、盈利因子、回撤、Sharpe、Monte-Carlo）以及每一笔模拟交易。优化在参数空间中进行网格搜索，按综合评分对最优参数集排序，并保存最佳结果。

• 已完成的优化 - 每次优化器运行的历史记录，包含其最佳参数和指标，让你了解已经尝试过什么以及什么胜出。

• 未平仓头寸 - 交易日志中的交易，以及连接时的 IBKR 实时头寸。

• 交易历史 - 每笔交易及其使用的策略（例如 bull call debit、bull put credit）、方向、规模、最大亏损、状态和已实现盈亏。

仪表盘每 8 秒刷新一次。自动交易（当你点击“启动”时）会通过仪表盘进程下纸面价差订单；其他执行仍由执行智能体负责。视图数据来自 data/trades.db；删除该文件即可重置为空日志。

Discord 远程控制

该机器人运行在这台 PC 上，与仪表盘并排，通过 http://127.0.0.1:8787 通信。来自手机（或任何 Discord 客户端）的斜杠命令随后驱动纸面自动交易，并将实时事件流式传回。

1. 在 discord.com/developers/applications 创建一个应用 → 机器人 → 将令牌复制到 .env 中，命名为 DISCORD_BOT_TOKEN。

2. OAuth2 → URL 生成器：权限范围 bot 和 applications.commands，权限 发送消息。打开该 URL，将机器人邀请到你拥有的服务器。

3. Discord 用户设置 → 高级 → 开发者模式。右键点击你的头像 → 复制用户 ID → DISCORD_ALLOWED_USER_IDS。右键点击服务器名称 → 复制服务器 ID → DISCORD_GUILD_ID（斜杠命令会立即出现）。可选：右键点击一个频道 → 复制频道 ID → DISCORD_LOG_CHANNEL_ID，用于发布实时成交 / 错误 / 启动 / 停止帖子。

4. 保持仪表盘运行，然后在第二个终端中：

pip install -e ".[dev]"          # once, so discord.py is in .venv
python -m dashboard.app          # already running is fine; restart it once
python -m scripts.discord_bot    # or: orb-discord

命令：/help、/status、/signals、/preview、/positions、/trades、/auto start|stop|status、/optimise（仅排名，不应用）、/nightly（默认为试运行）。如果 ACCOUNT_MODE=LIVE，/auto start 会被拒绝。没有任何 Discord 命令会下真实 IBKR 订单。

验证 IBKR 连接

在 IB Gateway/TWS 运行并登录模拟账户的情况下：

python -m scripts.check_ibkr

它会打印解析后的主机/端口/模式，进行连接，并获取一个示例报价以及你的账户摘要。如果失败，它会准确告诉你需要检查什么。完整操作指南见 docs/IBKR_SETUP.md。

历史数据（回测）

IBKR 每次请求只返回大约一个月的 5 分钟 K 线。要在本地缓存一年的 SPY 历史数据（供仪表盘回测 / 优化器1 年回看使用）：

python -m scripts.fetch_history --symbol SPY --days 365

K 线会写入 data/history/SPY_5mins.csv。如果缓存已经覆盖了所请求的回看期，重新运行该命令会复用缓存。

手动运行服务器

每个服务器通过 stdio 提供 MCP 服务，通常由客户端启动，但你可以直接对其中一个进行冒烟测试：

python -m servers.market_data_mcp.server    # (uv: uv run python -m ...)

四个智能体（MCP 工具组）

交易循环（客户端如何使用这些工具）

1. market-data-mcp.get_session_orb -> 当前活跃窗口的突破方向 + 强度。

2. market-data-mcp.classify_regime -> 趋势 vs 区间（选择借方 vs 贷方差价）。

3. research-mcp.learn_from_history -> 该窗口/市场状态是否具有正期望值？

4. execution-mcp.preview_spread -> 按风险上限规模化的限定风险垂直价差。

5. execution-mcp.place_spread -> 提交组合订单 + 括号单 SL/TP（默认为纸面）。

6. 结果通过 research-mcp.log_trade 记录；optimiser-mcp 会优化参数。

上线（刻意设置得很困难）

真实交易需要同时满足：

• ACCOUNT_MODE=live, 以及

• LIVE_TRADING_CONFIRM=I_UNDERSTAND_THE_RISK

并将 IBKR_PORT 指向你的真实 TWS/Gateway 端口。如果只设置了其中一个，执行器会拒绝交易。先在模拟账户上运行数周。

Docker

Python 技术栈（仪表盘、Discord 机器人、MCP 服务器、配置）是一个镜像。IB Gateway 仍是独立的社区容器，因为它是 Java 桌面应用。

copy .env.example .env            # then set IB_GATEWAY_USER / IB_GATEWAY_PASSWORD
docker compose up -d --build      # dashboard: http://127.0.0.1:8787

# Optional Discord bot (needs DISCORD_* in .env)
docker compose --profile discord up -d

推送 main 分支还会将镜像发布到 GitHub Container Registry：

docker pull ghcr.io/<owner>/options-orb-mcp:latest

镜像中的一次性命令：

docker compose run --rm dashboard demo     # offline demo (no IBKR)
docker compose run --rm dashboard check    # IBKR connectivity

MCP 服务器通常仍在主机上运行（Cursor/Claude 通过 stdio 启动它们）。如果你想要执行它们，镜像中也安装了它们：

docker compose exec dashboard python -m servers.market_data_mcp.server

另一台 PC（克隆这台机器）

不要复制 .venv、.env 或 .cursor/mcp.json——它们与这台电脑的 Python 路径和密钥绑定。克隆仓库，然后在新 PC 上：

git clone <your-repo-url> "Options Trading"
cd "Options Trading"
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
copy .env.example .env
# edit .env: IBKR_PORT=4002, ACCOUNT_MODE=paper
python -m scripts.setup
pytest -q

然后仅在该 PC 上：

1. 安装 IB Gateway，登录同一个模拟账户，在端口 4002 上启用 API（docs/IBKR_SETUP.md）。API 是 127.0.0.1——Gateway 必须在该机器上运行。

2. 可选：从这台 PC 复制 data/history/SPY_5mins.csv，以跳过长时间的历史数据下载。否则：python -m scripts.fetch_history --symbol SPY --days 365

3. 不要复制 data/trades.db，除非你想让这台 PC 使用现有的交易日志。缺少该文件即是一本全新的模拟账本。

4. 运行 python -m dashboard.app → http://127.0.0.1:8787，然后启动自动交易。

5. 夜间优化器（23:30 GMT）：python -m scripts.nightly_optimise --install-task

6. 重启 Cursor，让 MCP 服务器读取 .cursor/mcp.json。

用 python -m scripts.check_ibkr 确认。Windows 夏令时变更后，重新运行 --install-task。

仓库结构

core/            shared library (config, models, db, pricing, risk, strategy, ibkr)
servers/         one MCP server per agent
dashboard/       read-only web GUI (Starlette API + single-page UI)
configs/         per-window ORB parameters
scripts/         setup / demo / check_ibkr / discord_bot / nightly_optimise
tests/           unit tests (pricing, ORB, risk, metrics)
data/            SQLite journal + backtest artifacts (gitignored)
docker/          container entrypoint
Dockerfile       Python stack image (dashboard, Discord, MCP servers)
docker-compose.yml  IB Gateway + dashboard (+ optional Discord)