t-invest-mcp

Твой портфель Т-Инвестиций — в диалоге с AI.

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

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

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

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

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

Нужен Node.js ≥ 22 и аккаунт Т-Инвестиций.

1. Токен. В настройках Т-Инвестиций выпусти токен «только чтение». «Подтверждение сделок кодом» должно быть выключено. Токен показывается один раз; живёт 3 месяца с последнего использования.

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

   claude mcp add t-invest \
     -e TINKOFF_API_TOKEN=<ваш-токен> \
     -- npx -y t-invest-mcp
   

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

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

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

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

   </details>

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

   Переменная	Что включает
   TINKOFF_SANDBOX=true	Песочница: виртуальный счёт на реальных котировках — безопасная обкатка (нужен отдельный sandbox-токен)
   TINKOFF_ALLOW_TRADING=true	Торговля: выставление/отмена заявок, каждая сделка — с вашего подтверждения (нужен full-access токен)
   TINKOFF_OUTPUT_DIR=<путь>	Куда складывать файловые выгрузки (по умолчанию — папка проекта)
   TINKOFF_CONFIRM=off	Отключить диалог подтверждения сделок — только для песочницы

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

Готовое из коробки: ритуалы

Не хочешь придумывать запросы — в сервер зашиты готовые рецепты. В Claude Code они появляются как slash-команды /t-invest:<имя>:

Ритуал	Что делает
weekly [сумма]	Дайджест недели: что выросло/упало и почему, события впереди; если указать сумму пополнения — план докупок
monthly	Итоги месяца: честная доходность (XIRR с учётом пополнений), выплаты, комиссии + календарь выплат
quarterly	Обзор портфеля + проверка, не пора ли ребалансировать

И отдельные команды под конкретные задачи:

Команда	Что делает
portfolio_review	Полный обзор: структура, концентрация, риски
payout_calendar	Купоны и дивиденды на N месяцев вперёд, средняя выплата в месяц
bond_picker <сумма> <горизонт>	Подбор облигаций: доходность с НКД, фильтр оферт, лесенка
rebalance_check	Дрейф от целевых долей + план сделок в лотах (без исполнения)
invest_cash <сумма>	Пришла зарплата: куда докупить, чтобы приблизиться к целям
position_deep_dive <тикер>	Разбор бумаги: фундаментал, прогнозы, выплаты, динамика
tax_helper [год]	Налоги за год + кандидаты на льготу долгосрочного владения
div_screener [мин. %]	Скрининг дивидендных акций MOEX
monthly_report, weekly_digest, fire_progress	Составные части ритуалов — можно вызывать отдельно
feedback [тема]	Что-то не работает? Соберёт репорт с диагностикой для разработчиков (без токена и личных данных)

Все команды анализируют и предлагают — ни одна не совершает сделок сама.

Нашли проблему? /t-invest:feedback

Команда сама собирает репорт для разработчиков: диагностику сервера (get_server_info — версия, режимы, окружение), шаги воспроизведения и точные тексты ошибок из диалога. Перед сохранением покажет вам текст и спросит, маскировать ли номера счетов и суммы — токен не попадает в репорт никогда. Результат ложится в feedback/FEEDBACK-<дата>-<тема>.md; дальше по желанию — GitHub issue в один шаг или отправьте файл сами.

Своя стратегия

Главное свойство сервера: он не навязывает методологию. Команды выше — это бонус, а не рамки. Под капотом — 20+ инструментов-кирпичиков (портфель, операции, котировки, купоны, фундаментал, прогнозы…), из которых модель собирает ответ на любой твой вопрос:

• Просто спрашивай. «Какая у меня доля валютных активов?», «сравни мои нефтяные бумаги по P/E», «что будет с купонами, если продам половину ОФЗ?» — без всяких команд.

• Опиши свои правила текстом. Положи свою стратегию в CLAUDE.md проекта («не больше 10% на эмитента», «дивиденды реинвестирую в облигации», «новые позиции — только после разбора отчётности») — и агент будет учитывать её в каждом ответе.

• Целевые доли — если нужны. Файл portfolio-target.json в корне проекта включает ребалансировку и план докупок. Минимум — только доли классов; byTicker и финансовые цели (goals) — опциональные надстройки. Эталон: MCP-ресурс t-invest://portfolio-target/example.

  { "targets": { "shares": 55, "bonds": 30, "etf": 10, "cash": 5 } }
  

• Данные — в свои руки. Каждый инструмент умеет выгружать результат в файл (outputPath, CSV/JSON) — сырые данные не съедают контекст диалога, а попадают на диск для pandas/Excel/чего угодно. get_operations при этом выкачивает всю историю операций, get_candles — годы свечей, а download_history_archive забирает минутки целыми годами (1 запрос = 1 год; доступные годы покажет get_history_archive_years). Дальше — любая своя аналитика: бэктесты, графики, отчёты.

Торговля (опционально, по умолчанию выключена)

Если хочешь не только анализировать, но и исполнять — включи явно:

TINKOFF_ALLOW_TRADING=true   # регистрирует place_order / cancel_order

Понадобится full-access токен. Защита трёхслойная:

1. Подтверждение в самом сервере (включено по умолчанию): перед заявкой — диалог человеку через MCP elicitation; клиенты без поддержки elicitation получают отказ. Отключение — TINKOFF_CONFIRM=off (рекомендуется только для песочницы).

2. Ask-правила Claude Code (клиентский слой, срабатывает ещё до вызова):

   {
     "permissions": {
       "allow": ["mcp__t-invest"],
       "ask": ["mcp__t-invest__place_order", "mcp__t-invest__cancel_order"]
     }
   }
   

   Приоритет deny → ask → allow гарантирует промпт в любом режиме, включая bypassPermissions. MCP tool annotations (destructiveHint) — лишь подсказки, Claude Code их не учитывает.

3. Песочница для обкатки:

   TINKOFF_API_TOKEN=<sandbox-токен> TINKOFF_SANDBOX=true TINKOFF_ALLOW_TRADING=true
   

   Счета/портфель/заявки уходят в песочницу (виртуальные деньги, реальные котировки), появляются sandbox_* инструменты. Попроси агента: «открой sandbox-счёт, положи миллион и собери модельный портфель 60/40».

Справочник

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

Переменная	Значение	Описание
TINKOFF_API_TOKEN	обязательна	Токен T-Invest API (read-only достаточно для базового режима)
TINKOFF_SANDBOX	true/false	Песочница: счета/портфель/заявки идут в sandbox, регистрируются sandbox_* tools. Нужен sandbox-токен
TINKOFF_ALLOW_TRADING	true/false	Регистрирует place_order/cancel_order. В боевом режиме — реальные деньги!
TINKOFF_CONFIRM	off	Отключает встроенное elicitation-подтверждение сделок (по умолчанию включено)
TINKOFF_OUTPUT_DIR	путь	Корень для файловых выгрузок outputPath (по умолчанию — cwd сервера, т.е. корень проекта)

Tools

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

Tool	Описание
get_accounts	Список брокерских счетов
get_portfolio	Портфель: суммы по классам активов, доходность, позиции с тикерами
get_operations	Операции (сделки, дивиденды, купоны, комиссии); с outputPath — вся история
find_instrument	Поиск инструмента по тикеру/ISIN/FIGI/названию
get_instrument	Карточка инструмента (лот, валюта, биржа, assetUid; для облигаций — номинал, погашение, НКД)
get_last_prices	Последние цены (батч), с признаком единицы котировки
get_candles	Свечи OHLCV (1min…month); с outputPath — весь период чанками
get_order_book	Стакан заявок
get_dividends	Дивиденды: история и анонсы
get_bond_coupons	Купонный календарь облигации
get_accrued_interests	НКД облигации
get_bond_events	События облигации: купоны, оферты, погашение
get_asset_fundamentals	Фундаментал: P/E, EV/EBITDA, ROE, долги, дивдоходность и др.
get_forecasts	Консенсус-прогнозы и таргеты аналитиков
get_trading_schedules	Расписание торгов на неделю
get_active_orders	Активные заявки
download_history_archive	Годовые архивы минутных свечей (1 запрос = 1 год) → единый CSV
get_history_archive_years	Какие годы архивов доступны по инструменту (и их размер)
download_trades_archive	Обезличенные сделки за торговый день → CSV
get_server_info	Диагностика сервера: версия, режимы, окружение (для фидбэка)

Торговые (TINKOFF_ALLOW_TRADING=true): place_order, cancel_order. Песочница (TINKOFF_SANDBOX=true): sandbox_open_account, sandbox_pay_in, sandbox_close_account.

Выгрузка в файл — детали

Каждый read-tool принимает outputPath (путь относительно TINKOFF_OUTPUT_DIR) и outputFormat (json/csv). Сервер пишет результат на диск, в диалог возвращает summary (savedTo, records, bytes, sample). Запись возможна строго внутри корня выгрузок; прогресс долгих выгрузок виден в клиенте.

portfolio-target.json — полный формат

{
  "targets": { "shares": 55, "bonds": 30, "etf": 10, "cash": 5 },
  "byTicker": { "SBER": 10 },
  "goals": [
    { "name": "FIRE", "targetAmount": 30000000, "targetDate": "2035-01-01",
      "monthlyContribution": 100000, "expectedAnnualReturnPct": 8 }
  ]
}

Классы targets суммируются к 100; фонды денежного рынка (LQDT и т.п.) допустимо относить к cash. goals — массив, целей может быть несколько; нужен только командам прогресса (fire_progress, ритуал monthly).

Построен на официальном SDK @tinkoff/invest-js (gRPC).

Disclaimer

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

License

Apache 2.0