mcp-ibkr

Собственный MCP-сервер (Model Context Protocol) для подключения Claude Code к Interactive Brokers (IBKR), начиная с режима только чтение на аккаунте Paper Trading.

Статус проекта: 12 из 12 фаз завершено. См. раздел «Текущее состояние».

1. Что это за проект

Мост между Claude Code и IBKR: Claude Code запускает этот сервер, сервер предоставляет «инструменты» (функции с именем и описанием), и Claude использует их, когда пользователь запрашивает информацию об аккаунте, позициях или рынке. Ни один инструмент не общается с IBKR напрямую: все они проходят через централизованный слой интеграции.

Related MCP server: IB Portfolio Tracker MCP Server

2. Архитектура

Claude Code (cliente MCP)
      │  stdio / JSON-RPC
      v
Servidor MCP (src/server.py)
      │
      v
Tool Registry (src/tools/*)
      │
      v
Capa de integración IBKR (src/ibkr/*)
      │  ib_async → socket TCP
      v
IB Gateway (Paper Trading, puerto 4002)
      │
      v
Interactive Brokers

3. Структура папок

mcp-ibkr/
├── src/
│   ├── server.py          # Punto de entrada del servidor MCP
│   ├── ibkr/
│   │   └── connection.py     # UNICO lugar que habla con ib_async / IB Gateway
│   ├── tools/
│   │   ├── registry.py       # Registro central: conecta archivos de herramienta con el servidor
│   │   ├── account/            # Saldo, resumen de cuenta, verificar conexión
│   │   ├── market/              # Precio, cotización, históricos
│   │   ├── positions/            # Posiciones abiertas, P&L
│   │   └── orders/                # Consultar (activa) + crear/cancelar (ACTION, deshabilitadas)
│   ├── config/
│   │   └── settings.py       # Carga .env, rechaza arrancar en config insegura
│   └── utils/
│       └── risk.py            # RiskLevel: READ_ONLY / ACTION
├── tests/
├── .env.example
├── .gitignore
├── .mcp.json          # Registro del servidor para Claude Code (scope project)
├── pyproject.toml      # Configuracion de pytest
├── requirements.txt     # Dependencias exactas (pip freeze)
└── README.md

4. Требования

• Python 3.11+ (проверено на 3.14).

• Git.

• curl (для загрузки get-pip.py в разделе 5 и установщика IB Gateway в разделе 6).

• Установленный IB Gateway с запущенной сессией Paper Trading (см. раздел 6).

5. Установка и настройка

cd ~/mcp-ibkr

# Crear entorno virtual aislado para este proyecto
python3 -m venv --without-pip .venv

# Instalar pip dentro del venv (no viene incluido con --without-pip)
curl -sS https://bootstrap.pypa.io/get-pip.py -o /tmp/get-pip.py
.venv/bin/python3 /tmp/get-pip.py

# Instalar dependencias del proyecto
.venv/bin/python3 -m pip install -r requirements.txt

# Configuración local (nunca se sube a Git)
cp .env.example .env

Примечание о requirements.txt: мы устанавливаем напрямую только 4 пакета (mcp, ib_async, python-dotenv, pytest), но в файле гораздо больше строк, потому что pip freeze включает также зависимости этих пакетов (зависимости их зависимостей). Это нормально — это не значит, что проект использует все эти библиотеки напрямую.

Примечание: в системах Debian/Ubuntu python3 -m venv сам по себе может не сработать, если отсутствует системный пакет python3-venv (устанавливается командой sudo apt install python3-venv). Если у вас нет доступа к sudo, комбинация --without-pip + ручная установка pip внутри venv (шаги выше) даёт такую же изолированную среду без необходимости прав администратора.

6. Подключение к IBKR (Paper Trading)

1. Установите IB Gateway (официальная загрузка, stable-standalone):

   curl -o ibgateway-stable-standalone-linux-x64.sh \
     https://download.interactivebrokers.com/installers/ibgateway/stable-standalone/ibgateway-stable-standalone-linux-x64.sh
   chmod u+x ibgateway-stable-standalone-linux-x64.sh
   ./ibgateway-stable-standalone-linux-x64.sh

2. Откройте его и войдите, явно выбрав «Paper Trading» (не «Live Trading»), используя свой логин/пароль Paper Trading.

3. Убедитесь, что порт API — 4002 (Paper). Подтвердить можно так:

   ss -ltnp | grep 4002   # deberia aparecer un proceso "java" escuchando

4. Скопируйте .env.example в .env (если ещё не сделали) и при необходимости скорректируйте значения, если ваша конфигурация отличается.

Почему это безопасно: src/config/settings.py отказывается запускаться, если IBKR_PORT не равен точно 4002, а также если IBKR_PAPER_TRADING_CONFIRMED не содержит true. Кроме того, соединение (src/ibkr/connection.py) открывается с readonly=True, из-за чего IB Gateway отклоняет любые попытки отправки ордеров на уровне API, даже до того, как появятся инструменты для ордеров.

7. Настройка Claude Code

Сервер зарегистрирован в .mcp.json (в корне проекта) с областью project. Это означает, что файл версионируется в Git, и любой, кто откроет этот репозиторий в Claude Code, увидит предложенный сервер — но он не запускается автоматически: Claude Code помечает его как «Pending approval», пока вы не откроете сессию внутри этой папки и не одобрите его.

cd ~/mcp-ibkr
claude    # al iniciar, Claude Code te preguntará si confías en mcp-ibkr

Чтобы в любой момент проверить статус сервера:

claude mcp list
claude mcp get mcp-ibkr

Если когда-нибудь захотите его удалить:

claude mcp remove mcp-ibkr -s project

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

9. Как добавить / изменить / удалить / отключить инструмент

Каждый инструмент — это один файл внутри src/tools/<категория>/, имеющий следующий вид (см. src/tools/account/verificar_conexion_ibkr.py как реальный пример):

from mcp.types import ToolAnnotations
from src.utils.risk import RiskLevel

NAME = "mi_herramienta"
DESCRIPTION = "Que hace, cuando usarla, que devuelve, si modifica la cuenta."
ANNOTATIONS = ToolAnnotations(readOnlyHint=True, openWorldHint=True)
ENABLED = True
RISK_LEVEL = RiskLevel.READ_ONLY  # o RiskLevel.ACTION si modifica algo

def mi_herramienta(parametro: str) -> str:
    return "resultado"

Функция должна называться так же, как NAME — так центральный реестр (src/tools/registry.py) находит её автоматически. Если RISK_LEVEL — ACTION, то помимо ENABLED = True также требуется IBKR_ENABLE_ACTION_TOOLS=true в .env (см. раздел 11) — два независимых ключа, намеренно.

Об ANNOTATIONS: destructiveHint и idempotentHint имеют значение только когда readOnlyHint=False (так указано в спецификации MCP) — поэтому для инструмента только для чтения достаточно readOnlyHint и openWorldHint. Добавляйте их только если RISK_LEVEL — ACTION, как в src/tools/orders/crear_orden.py.

Добавление инструмента

1. Создайте файл в соответствующей категории (или создайте новую категорию, см. ниже).

2. Добавьте имя файла (без .py) в список TOOLS в __init__.py этой категории.

3. Перезапустите сессию Claude Code, чтобы он его подхватил (Claude Code читает инструменты один раз, при запуске сервера; claude mcp list только проверяет статус соединения, ничего не перезагружает).

Изменение инструмента

Отредактируйте напрямую его файл — DESCRIPTION, параметры функции, внутреннюю логику и т.д. registry.py трогать не нужно.

Удаление инструмента

Удалите файл и уберите его имя из TOOLS в __init__.py его категории.

Отключение инструмента (без удаления)

Установите ENABLED = False в его файле. registry.py автоматически его пропустит.

Создание новой категории

Создайте папку src/tools/<категория>/ с __init__.py, определяющим TOOLS: list[str] = [...], и добавьте имя категории в CATEGORIES в src/tools/registry.py.

10. Тестирование

cd ~/mcp-ibkr
.venv/bin/python3 -m pytest tests/ -v

• tests/test_server.py — сервер запускается и предоставляет ожидаемые инструменты (то же самое, что увидел бы Claude Code при подключении); инструменты только для чтения не задают неприменимые аннотации; и каждый инструмент отвечает дружелюбным сообщением, если IBKR недоступен, вместо того чтобы допустить исключение.

• tests/test_settings.py — конфигурация отклоняет порт, отличный от 4002, и отсутствие IBKR_PAPER_TRADING_CONFIRMED.

• tests/test_connection.py — слой соединения сериализует попытки подключения (с имитацией IBKR, реальный Gateway не требуется): если два инструмента вызываются почти одновременно, никогда не выполняется две попытки соединения параллельно.

• tests/test_risk_system.py — инструменты ACTION (crear_orden, cancelar_orden) не регистрируются по умолчанию, а валидации ордера (количество, тип, цена) отклоняют недопустимые параметры.

• tests/test_ibkr_integration.py — реальное соединение с IB Gateway. Если Gateway не запущен, этот тест пропускается (не падает) — это ожидаемо, это не ошибка проекта.

Все тесты, связанные с ордерами, используют validar_parametros_orden изолированно (без обращения к IBKR) или зависят от того, что crear_orden отключён по умолчанию: ни один тест этого проекта не отправляет реальный ордер, даже в Paper Trading.

11. От Paper Trading к Live Trading

⚠️ Live Trading пока не поддерживается этим проектом, и crear_orden/cancelar_orden отключены по умолчанию. Ниже объясняются уровни безопасности, а не приглашение активировать их не подумав.

Есть три независимых уровня, которые не позволяют случайно отправить реальный ордер:

1. Обязательный порт 4002 — src/config/settings.py отказывается запускаться, если IBKR_PORT не равен точно порту Paper Trading. В этой версии проекта нет ни одного пути в коде для использования порта 4001 (Live).

2. Двойной ключ для инструментов ACTION — crear_orden и cancelar_orden требуют ENABLED = True в своём собственном файле и IBKR_ENABLE_ACTION_TOOLS=true в .env. Ни один из них не активирован по умолчанию. Оба читаются только при запуске сервера: если вы измените их при уже запущенном сервере, нужно перезапустить сессию Claude Code, чтобы изменение вступило в силу.

3. Соединение только для чтения на уровне API — пока IBKR_ENABLE_ACTION_TOOLS имеет значение false, src/ibkr/connection.py подключается с readonly=True: IB Gateway отклоняет любой ордер, даже если кому-то удалось обойти два предыдущих уровня.

Если в будущем вы решите включить отправку ордеров в Paper Trading, путь будет таким: пересмотреть и усилить валидации в src/tools/orders/crear_orden.py, установить IBKR_ENABLE_ACTION_TOOLS=true в .env и ENABLED = True в файлах ордеров. Поддержка реального Live Trading не реализована и не планируется в этом проекте — потребовался бы полностью отдельный обзор безопасности, прежде чем это рассматривать.

12. Текущее состояние

• Фаза 1 — Архитектура и концепции

• Фаза 2 — Минимальная структура проекта

• Фаза 3 — Среда разработки

• Фаза 4 — Минимальный MCP-сервер

• Фаза 5 — Подключение Claude Code к MCP

• Фаза 6 — Первый тестовый инструмент

• Фаза 7 — Подключение к IB Gateway (Paper Trading)

• Фаза 8 — Инструменты запросов

• Фаза 9 — Система валидации и рисков

• Фаза 10 — Инструменты ордеров (заблокированы)

• Фаза 11 — Полное тестирование

• Фаза 12 — Финальная документация