Options ORB MCP System

Система MCP серверов, ориентированная в первую очередь на демо-режим, предоставляет LLM-клиенту (Cursor / Claude Desktop) инструменты анализа рынка, исследований, оптимизации и исполнения сделок. Она торгует вертикальными опционными спредами с ограниченным риском, управляемыми сигналом Opening Range Breakout (ORB), оптимизированными по торговым сессиям (Asia / London / New York), со строгими ограничениями риска, рассчитанными на капитал ~£1000.

Предупреждение о риске. Это образовательное программное обеспечение, а не финансовая рекомендация. Торговля опционами сопряжена с риском потери капитала. Система по умолчанию использует бумажный счёт и отказывается размещать реальные заявки, пока вы намеренно не переключите два независимых предохранительных выключателя. «Стабильная доходность» — это цель дизайна, а не гарантия.

Почему дизайн выглядит так

• В вашем бриффинге упоминались ORB, торговые сессии, SL/TP и MetaTrader. Реальные опционы (страйки/экспирации/греки) не живут на MT5, поэтому здесь используется Interactive Brokers (бумажный API + доступ из UK + опционы США).

• £1000 означает только спреды с ограниченным риском (вертикальные). Пробой ORB на базовом активе — это направленный сигнал; исполнитель размещает спред.

• Торговые сессии переосмыслены для американских опционов: Asia = ночной диапазон globex, London = EU/предрыночная торговля, New York = классический 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 с включённой бумажной торговлей, а также запущенные TWS или IB Gateway с включённым API (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, рассчитывает размер спреда с ограниченным риском, симулирует бумажное исполнение, записывает его в журнал, затем прогоняет бэктест, оптимизацию и walk-forward валидацию стратегии — всё в офлайне.

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; они также доступны в вашем PATH после pip install -e ..

Панель управления (GUI)

Read-only веб-панель даёт наглядный обзор всего сразу:

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

Она показывает:

• Карточки счетов — окружение (бейдж PAPER/LIVE), подключение к IBKR, дневной P&L, бюджет риска на сделку, открытые позиции и статус ежедневного аварийного рубильника.

• Кривая капитала — совокупный P&L закрытых сделок от вашего стартового капитала.

• Живые сигналы — текущее значение ORB по каждой торговой сессии (с переключателем «Demo data», чтобы работало без IBKR).

• Производительность по сессиям и по стратегиям — процент выигрышных сделок, математическое ожидание, профит-фактор и общий P&L, чтобы вы могли видеть, какие окна ORB и какие типы спредов работают.

• Автоторговля (кнопка Play) — элемент управления запуском/остановкой, который автоматически выполняет цикл входа по ORB: каждый интервал он оценивает активную торговую сессию, и если подходящий пробой проходит все проверки риска, размещает спред с рассчитанным размером (бумажный или симуляционный) и записывает его в журнал. Входы используют выбранный вами набор параметров (рейтинг оптимизатора, история оптимизаций или Use these for trading в расширенных параметрах). Пока вы не выбрали, применяются значения по умолчанию из windows.json. Он открывает до 3 сделок на торговую сессию (максимум 9 в день по Asia / London / New York), соблюдает лимит на сделку и ежедневный аварийный рубильник, а также показывает живой журнал активности. Отключено для LIVE-счетов в целях безопасности — только бумажная/симуляционная торговля.

• Бэктестинг и симуляция — выберите символ, торговую сессию и период ретроспективы, затем нажмите Run backtest для получения исторических данных (живая история IBKR или демо-данные в офлайне) и симуляции стратегии спреда ORB. Вы получаете симулированную кривую капитала, полные метрики (процент выигрышных сделок, математическое ожидание, профит-фактор, просадка, Sharpe, Monte-Carlo) и каждую симулированную сделку. Optimise выполняет grid-поиск по пространству параметров, ранжирует лучшие наборы по сбалансированному баллу и сохраняет лучший.

• Выполненные оптимизации — история каждого запуска оптимизатора с его лучшими параметрами и метриками, чтобы вы могли видеть, что было испробовано и что победило.

• Открытые позиции — сделки из журнала плюс живые позиции IBKR при подключении.

• История сделок — каждая сделка с использованной стратегией (например, bull call debit, bull put credit), направлением, размером, максимальным убытком, статусом и реализованным P&L.

Она обновляется каждые 8 секунд. Автоторговля (когда вы её запускаете) размещает бумажные спреды через процесс панели; остальное исполнение остаётся за исполнительным агентом. Представление заполняется из data/trades.db; удалите этот файл, чтобы сбросить журнал к пустому.

Удалённое управление через Discord

Бот запускается на этом ПК рядом с панелью управления и общается с http://127.0.0.1:8787. Слэш-команды с вашего телефона (или любого Discord-клиента) управляют бумажной автоторговлей и передают живые события обратно.

1. Создайте приложение на discord.com/developers/applications → Bot → скопируйте токен в .env как DISCORD_BOT_TOKEN.

2. OAuth2 → URL Generator: scopes bot и applications.commands, право Send Messages. Откройте URL и пригласите бота на свой сервер.

3. Discord User Settings → Advanced → Developer Mode. Нажмите правой кнопкой на свой аватар → Copy User ID → DISCORD_ALLOWED_USER_IDS. Правой кнопкой на имя сервера → Copy Server ID → DISCORD_GUILD_ID (слэш-команды появятся сразу). Необязательно: правой кнопкой на канал → Copy Channel ID → DISCORD_LOG_CHANNEL_ID для публикации событий fill / error / start / stop.

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 (по умолчанию dry-run). /auto start отклоняется, если ACCOUNT_MODE=LIVE. Не существует Discord-команды, которая размещает реальный IBKR-ордер.

Проверка подключения к IBKR

При запущенных IB Gateway/TWS и входе в бумажный аккаунт:

python -m scripts.check_ibkr

Он выводит разрешённые хост/порт/режим, подключается и получает пример котировки, а также сводку по вашему счёту. При сбое он точно говорит, что проверить. Полное руководство в docs/IBKR_SETUP.md.

Исторические данные (бэктесты)

IBKR возвращает только около месяца 5-минутных баров за один запрос. Чтобы закэшировать год истории SPY локально (используется бэктестом панели / оптимизатором для периода ретроспективы 1 год):

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

Бары записываются в data/history/SPY_5mins.csv. Повторный запуск команды использует кэш, если он уже покрывает запрошенный период ретроспективы.

Запуск сервера вручную

Каждый сервер общается по MCP через stdio и обычно запускается клиентом, но вы можете быстро проверить один сервер напрямую:

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 -> тренд или диапазон (выбирает дебетовый или кредитный спред).

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). Они установлены в образе, если вы захотите выполнить их через exec:

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

Другой ПК (клонирование этой машины)

Не копируйте .venv, .env или .cursor/mcp.json — они привязаны к путям Python и секретам этого компьютера. Склонируйте репозиторий, затем на новом ПК:

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

Затем только на этом ПК:

1. Установите IB Gateway, войдите в тот же бумажный аккаунт, включите API на порту 4002 (docs/IBKR_SETUP.md). API — это 127.0.0.1 — Gateway должен работать на этой машине.

2. Необязательно: скопируйте data/history/SPY_5mins.csv с этого ПК, чтобы пропустить долгую загрузку истории. В противном случае: python -m scripts.fetch_history --days 365

3. Не копируйте data/trades.db, если только не хотите получить журнал этого ПК. Отсутствующий файл — это новый бумажный реестр.

4. python -m dashboard.app → http://127.0.0.1:8787, затем нажмите Start для запуска автоторговли.

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)