IBKR MCP Server

Сервер протокола контекста модели (MCP), который предоставляет ИИ-моделям безопасный доступ к торговым данным и функционалу Interactive Brokers (IBKR) через TWS API.

⚠️⚠️⚠️ Отказ от ответственности ⚠️⚠️⚠️

Это программное обеспечение предназначено для образовательных целей и разработки. Используйте его на свой страх и риск. Авторы не несут ответственности за любые финансовые потери, понесенные в результате использования данного программного обеспечения. Всегда тестируйте на демо-счете (paper trading) перед использованием реальных денег.

Related MCP server: IBKR TWS MCP Server

🚀 Функции

• Управление счетом: получение позиций, сведений о портфеле и сводок по счету

• Рыночные данные: получение исторических ценовых данных и рыночной информации в реальном времени

• Торговые операции: размещение ордеров, управление позициями и отслеживание исполнения

• Интеграция с MCP: бесшовная интеграция с ИИ-моделями, поддерживающими протокол MCP

• One-shot CLI: подключение-выполнение-отключение для каждой команды для быстрого написания скриптов

• Автоматический запуск TWS (macOS): одна команда для запуска TWS и автоматического ввода TOTP 2FA

• Навык Claude Code: торговля на естественном языке через входящий в комплект skills/ibkr-trading

• Функции безопасности: режим «только чтение», настраиваемые торговые ограничения и комплексная проверка

• Высокая доступность: автоматическое переподключение, мониторинг пульса (heartbeat) и корректная обработка ошибок

📋 Предварительные требования

• Python 3.10+

• Interactive Brokers TWS или IB Gateway

• Активный счет IBKR (для тестирования рекомендуется демо-счет)

🛠️ Установка

1. Клонируйте репозиторий:

   git clone https://github.com/happy-shine/ibkr_mcp.git
   cd ibkr_mcp

2. Установите зависимости:

   pip install -r requirements.txt

3. Настройте TWS/IB Gateway:

   • Включите API-соединения в настройках TWS/Gateway

   • Установите порт сокета (по умолчанию: 7497 для демо-счета, 7496 для реального)

   • При необходимости настройте доверенные IP-адреса

4. Настройте сервер:

   cp config/config.yaml.example config/config.yaml
   # Edit config/config.yaml with your settings

🚀 Использование

Вариант A: MCP Server

python run.py

Сервер выполнит следующее:

1. Подключится к TWS/IB Gateway

2. Запустит MCP-сервер на настроенном порту

3. Начнет мониторинг пульса

4. Будет записывать все действия в лог

Вариант B: One-shot CLI

Легковесный CLI, который подключается для каждой команды и завершает работу — подходит для shell-скриптов или разовых запросов.

python cli.py positions
python cli.py summary
python cli.py quote AAPL
python cli.py history AAPL --duration "1 M" --bar "1 day"
python cli.py buy AAPL 10 --type MKT --confirm
python cli.py orders

Запустите python cli.py --help для получения полного списка команд.

Примечание о данных котировок: Если у вас нет подписки на рыночные данные в реальном времени, quote возвращает данные последнего дневного бара через исторические данные (без полей реального времени).

Вариант C: Автоматический запуск TWS (только для macOS)

start_tws.py запускает TWS через IBC, обнаруживает диалоговое окно двухфакторной аутентификации, генерирует TOTP-код с помощью pyotp и вводит его через AppleScript (osascript) — полностью автоматизированный вход без использования клавиатуры.

python start_tws.py          # launch and auto-fill 2FA
python start_tws.py --wait   # also block until API port 7496 is listening

Требования (macOS):

Настройка:

1. Установите IBC согласно инструкциям для macOS (обычно в ~/ibc/).

2. В файле ~/ibc/config.ini установите:

   • TradingMode=live (или paper)

   • SecondFactorDevice=Mobile Authenticator

   • Ваши учетные данные IBKR

3. Сохраните ваш секретный ключ TOTP IBKR (строка Base32 из QR-кода аутентификатора) в ~/.ibkr-totp-secret или экспортируйте его как TOTP_SECRET.

4. Предоставьте Терминалу (или вашему Python-лаунчеру) разрешение Универсальный доступ (Accessibility) в Системные настройки → Конфиденциальность и безопасность → Универсальный доступ — это необходимо для того, чтобы AppleScript мог взаимодействовать с окном TWS.

Примечание по платформе: start_tws.py полагается на AppleScript/osascript и работает только в macOS. Пользователям Linux/Windows следует использовать IBC напрямую или адаптировать уровень автоматизации графического интерфейса (например, xdotool в Linux, pywinauto в Windows).

Доступные инструменты MCP

Инструменты для работы со счетом

• get_positions() - Получить текущие позиции по счету

• get_account_summary() - Получить баланс счета и метрики

• get_portfolio() - Получить подробную информацию о портфеле

Инструменты для работы с рыночными данными

• get_historical_data(symbol, duration, bar_size) - Получить исторические ценовые данные

• get_market_data(symbol) - Получить рыночные данные в реальном времени

• get_quote_from_history(symbol) - Последний дневной бар в качестве котировки (подписка не требуется)

• get_contract_details(symbol) - Получить спецификации контракта

• get_option_chain - Получить данные по опционам

Инструменты для торговли

• place_order(symbol, action, quantity, order_type, ...) - Разместить ордера на покупку/продажу

• get_orders(status) - Получить историю и статус ордеров

• cancel_order(order_id) - Отменить ожидающие ордера

• get_trades() - Получить историю исполнения сделок

Примеры взаимодействия с ИИ

AI: "What are my current positions?"
→ Calls get_positions() tool

AI: "Buy 100 shares of AAPL at market price"
→ Calls place_order(symbol="AAPL", action="BUY", quantity=100, order_type="MKT")

AI: "Show me AAPL's price history for the last week"
→ Calls get_historical_data(symbol="AAPL", duration="1 W", bar_size="1 day")

🤖 Навык Claude Code

Сопутствующий навык находится в skills/ibkr-trading/SKILL.md. Он позволяет Claude Code выполнять команды CLI, указанные выше, на основе запросов на естественном языке (например, "show my positions", "quote AAPL").

Чтобы установить его, создайте символическую ссылку в директории навыков Claude Code:

ln -s "$(pwd)/skills/ibkr-trading" ~/.claude/skills/ibkr-trading

🔗 Полезные ссылки и авторы

• Interactive Brokers TWS API — официальный Python API (ibapi)

• IBC — Interactive Brokers Controller — автозапуск TWS (используется в start_tws.py)

• pyotp — библиотека TOTP/HOTP (используется в start_tws.py)

• Спецификация протокола контекста модели (MCP)

• Фреймворк FastMCP

• Claude Code — CLI для ИИ-парного программирования, использующий встроенный навык