bcs-mcp

Твой портфель БКС Мир инвестиций — в диалоге с AI.

MCP-сервер, который подключает Claude (Claude Code, Claude Desktop — и любой другой MCP-клиент) к BCS Trade API. Смотри портфель, котировки, стакан, свечи, анализируй позиции и планируй ребалансировку — обычными фразами, на русском.

Это не торговый робот и не «сигналы». Решения всегда принимаешь ты — сервер лишь даёт модели безопасный доступ к данным твоего брокерского счёта.

Собран по образу и подобию t-invest-mcp (аналогичный сервер для Т-Инвестиций) — та же модель безопасности и файловых выгрузок.

Почему это безопасно

• Read-only по умолчанию. Торговые операции даже не регистрируются, пока ты их явно не включишь. Достаточно токена «только для чтения».
• Сделки — только с твоего подтверждения. Если включишь торговлю, перед каждой заявкой сервер показывает диалог «Купить N шт. X?» — без явного «да» заявка не уйдёт.
• У БКС нет песочницы — поэтому торговый режим включай осознанно: каждая заявка реальная.
• Токен живёт в переменной окружения и никогда не попадает в код, логи и ответы сервера. Быстрый старт ниже кладёт его в конфиг клиента — для постоянного использования держи токен в системном keychain, рецепт: docs/secure-token.md.

Быстрый старт (5 минут)

Нужен Node.js ≥ 22 и брокерский счёт в БКС.

1. Токен. Войди в веб-версию БКС Мир инвестиций → «Профиль» → «Управление счетами» → нажми на брокерский счёт → «Токены API» → «Выпустить токен», тип «Только для чтения». Токен показывается один раз; живёт 90 дней. Токен привязан ровно к одному счёту.

2. Подключение к Claude Code — одной командой, установка не нужна (пакет bcs-mcp подтянется из npm):

   claude mcp add bcs \
     -e BCS_REFRESH_TOKEN=<ваш-токен> \
     -- npx -y bcs-mcp

   Для Claude Desktop тот же блок добавляется в Settings → Developer → Edit Config. Этот JSON подходит и любому другому MCP-клиенту (Cursor, VS Code, Windsurf и др.) — меняется только место, куда его вписать:

   {
     "mcpServers": {
       "bcs": {
         "command": "npx",
         "args": ["-y", "bcs-mcp"],
         "env": { "BCS_REFRESH_TOKEN": "<ваш-токен>" }
       }
     }
   }

   git clone https://github.com/human-turn/bcs-mcp && cd bcs-mcp
   npm install && npm run build
   # далее в командах выше вместо "npx -y bcs-mcp" → "node /path/to/bcs-mcp/dist/index.js"

   В такой минимальной конфигурации сервер строго read-only: смотреть и анализировать можно всё, торговать — нельзя (торговые операции даже не регистрируются). Торговля и файловые выгрузки включаются переменными в env — см. Переменные окружения, каждая выключена по умолчанию.

3. Проверка: спроси «покажи мой портфель БКС».

Готовое из коробки: slash-команды

В Claude Code появляются как /bcs:<имя>:

| Команда | Что делает | |---|---| | portfolio_review | Полный обзор: структура, концентрация, риски | | rebalance_check | Дрейф от целевых долей + план сделок в лотах (без исполнения) | | invest_cash <сумма> | Пришла зарплата: куда докупить, чтобы приблизиться к целям | | bond_picker <сумма> <горизонт> | Скрининг каталога облигаций: рейтинг, купон, доходность, лесенка | | fire_progress | Прогресс к целям (FIRE) из portfolio-target.json: прогноз, требуемый взнос | | position_deep_dive <тикер> | Разбор бумаги: карточка, динамика, моя позиция | | trades_review [дней] | Мои сделки за период: обороты, средние цены, комиссии | | weekly [сумма] | Недельный ритуал: дайджест + план докупок | | quarterly | Обзор портфеля + проверка ребалансировки | | feedback [тема] | Репорт о проблеме для разработчиков (без токена и личных данных) |

Все команды анализируют и предлагают — ни одна не совершает сделок сама. Целевые доли для ребалансировки задаются файлом portfolio-target.json в корне проекта (эталон — MCP-ресурс bcs://portfolio-target/example, формат совместим с t-invest-mcp).

Дивиденды и купоны BCS Trade API не отдаёт — рядом можно подключить публичный moex-mcp (MOEX ISS): команды это учитывают.

Переменные окружения

| Переменная | Значение | Описание | |---|---|---| | BCS_REFRESH_TOKEN | обязательна | Refresh-токен из ЛК БКС (90 дней, привязан к счёту) | | BCS_ALLOW_TRADING | true/false | Регистрирует place/edit/cancel_order. Нужен токен «для торговли и чтения». РЕАЛЬНЫЕ деньги! | | BCS_CONFIRM | off | Отключает elicitation-подтверждение сделок (по умолчанию включено; выключать не рекомендуется — песочницы нет) | | BCS_OUTPUT_DIR | путь | Корень для файловых выгрузок outputPath (по умолчанию — cwd сервера) |

Tools

Read-only (всегда):

| Tool | Описание | |---|---| | get_portfolio | Портфель: позиции с P&L, долями, стоимостью в RUB/USD/EUR; итоги по классам (срез term, по умолчанию T0) | | get_limits | Денежные и депо-лимиты: свободные средства по валютам (free = quantity − locked; снимок на начало дня) | | get_quotes | Котировки (батч): bid/offer, last, open/high/low, изменение за день | | get_order_book | Стакан L2 (глубина 20) | | get_recent_trades | Лента обезличенных сделок: новейшие limit (расширяемое окно), период from/to; полный период в файл — через outputPath | | get_candles | Свечи OHLCV (M1…MN); с outputPath — весь период чанками | | find_instrument | Карточки по тикерам/ISIN: лот, classCode, купоны, дивдоходность, рейтинги (одна карточка на бумагу; allBoards — все площадки) | | get_instruments_by_type | Каталог инструментов типа (акции/облигации/ETF/фьючерсы…), пагинация | | get_trading_schedule | Сессии инструмента на сегодня (МСК, отсортированы) | | get_trading_status | Открыт/закрыт инструмент сейчас + кросс-чек с расписанием (warning при расхождении) | | get_discounts | Маржинальные дисконты (long/short) | | get_orders | Список заявок (данные с 26.01.2026) | | get_order_status | Статус заявки по UUID или биржевому номеру | | get_trades | Мои исполненные сделки (данные с 26.01.2026) | | get_server_info | Диагностика сервера (для фидбэка) |

Торговые (BCS_ALLOW_TRADING=true): place_order, edit_order, cancel_order. Важно: количество в заявках — в штуках, не в лотах (лот — lotSize из find_instrument).

Выгрузка в файл

Каждый read-tool принимает outputPath (путь относительно BCS_OUTPUT_DIR) и outputFormat (json/csv). Сервер пишет результат на диск, в диалог возвращает summary. Для get_candles и get_instruments_by_type это включает выкачивание полного периода/каталога чанками. Запись возможна строго внутри корня выгрузок.

Ограничения BCS Trade API

• Нет истории денежных операций (полученные дивиденды, комиссии, пополнения) — только биржевые сделки. XIRR и налоговые отчёты поэтому невозможны.
• Нет песочницы.
• Один токен = один счёт (несколько счетов — несколько инстансов сервера).
• Списки заявок/сделок — только с 26.01.2026.

Disclaimer

Не является индивидуальной инвестиционной рекомендацией. Все торговые решения вы принимаете самостоятельно. place_order оперирует реальными деньгами — используйте BCS_ALLOW_TRADING=true осознанно и держите подтверждение сделок включённым.

License

Apache 2.0