# bcs-mcp

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

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

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

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

![Демо: портфель БКС на естественном языке — вопросы и покупка с подтверждением](docs/demo.gif)

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

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

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

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

1. **Токен.** Войди в веб-версию [БКС Мир инвестиций](https://lk.bcs.ru/) →
   «Профиль» → «Управление счетами» → нажми на брокерский счёт → «Токены API» →
   «Выпустить токен», тип **«Только для чтения»**. Токен показывается один раз;
   живёт 90 дней. Токен привязан ровно к одному счёту.
2. **Подключение к Claude Code** — одной командой, установка не нужна
   (пакет [`bcs-mcp`](https://www.npmjs.com/package/bcs-mcp) подтянется из npm):

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

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

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

   <details><summary>Вариант из исходников (для разработки)</summary>

   ```bash
   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"
   ```

   </details>

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

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

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

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

![Демо: квартальный ритуал одной командой](docs/demo-rituals.gif)

| Команда | Что делает |
|---|---|
| `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](https://github.com/cyberash-dev/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