# T-Invest MCP Server

MCP сервер для работы с API Т-Инвестиций (Тинькофф Инвестиции) из Claude и других LLM-клиентов.

Порт [t-invest-mcp-server](https://github.com/prikotov/t-invest-mcp-server) на Node.js.

## Инструменты (30)

### Управление счетами

| Инструмент | Параметры | Описание |
|---|---|---|
| `get_accounts` | — | Список брокерских счетов |
| `get_bank_accounts` | — | Список банковских счетов |
| `get_user_info` | — | Профиль пользователя (тариф, квал. инвестор) |
| `get_user_tariff` | — | Лимиты API (запросы/мин, стримы) |
| `get_portfolio` | `accountId`*, `tickers`? | Портфель по счёту с фильтрацией по тикерам |
| `get_positions` | `accountId`* | Позиции счёта (деньги, ценные бумаги, фьючерсы) |
| `get_withdraw_limits` | `accountId`* | Лимиты вывода средств |
| `get_margin_attributes` | `accountId`* | Маржинальные атрибуты (ликвидный портфель, начальная маржа) |
| `get_account_values` | `accountIds`* | Дополнительные показатели счетов |
| `pay_in` | `fromAccountId`*, `toAccountId`*, `amount`*, `currency`? | Пополнить брокерский счёт с банковского |
| `currency_transfer` | `fromAccountId`*, `toAccountId`*, `amount`*, `currency`? | Перевод между брокерскими счетами |

### Аналитика и инструменты

| Инструмент | Параметры | Описание |
|---|---|---|
| `get_asset_fundamentals` | `tickers`* | Фундаментальные показатели: P/E, ROE, EBITDA и др. (до 100 тикеров) |
| `get_last_prices` | `tickers`* | Текущие рыночные цены (до 100 тикеров) |
| `get_candles` | `ticker`*, `from`*, `to`*, `interval`? | Исторические свечи OHLCV (1min, 5min, 15min, hour, day, week, month) |
| `get_dividends` | `tickers`*, `from`?, `to`? | Дивидендный календарь (до 50 тикеров) |
| `get_bond_coupons` | `tickers`*, `from`?, `to`? | Купонные выплаты по облигациям (до 50 тикеров) |
| `get_consensus_forecasts` | `tickers`* | Консенсус-прогнозы аналитиков (до 50 тикеров) |
| `get_order_book` | `ticker`*, `depth`? | Стакан заявок (глубина 1–50, по умолчанию 10) |
| `get_trading_status` | `tickers`* | Статус торгов по тикерам (до 50) |
| `get_trading_schedules` | `exchange`?, `from`*, `to`* | Расписание торгов (по умолчанию MOEX) |
| `get_tech_analysis` | `ticker`*, `indicator`*, `from`*, `to`*, `interval`?, `length`? | Технический анализ: BB, EMA, RSI, MACD, SMA |
| `get_signals` | `tickers`?, `from`?, `to`?, `direction`?, `limit`? | Торговые сигналы |
| `get_max_lots` | `accountId`*, `ticker`*, `price`? | Максимальное количество лотов для покупки/продажи |

### История операций

| Инструмент | Параметры | Описание |
|---|---|---|
| `get_operations` | `accountId`*, `from`?, `to`?, `limit`? | История операций: сделки, дивиденды, комиссии |

### Торговые операции

| Инструмент | Параметры | Описание |
|---|---|---|
| `get_orders` | `accountId`* | Активные биржевые заявки |
| `post_order` | `accountId`*, `ticker`*, `direction`*, `quantity`*, `orderType`*, `price`? | Выставить заявку (купить/продать) |
| `cancel_order` | `accountId`*, `orderId`* | Отменить биржевую заявку |
| `get_stop_orders` | `accountId`* | Активные стоп-заявки |
| `post_stop_order` | `accountId`*, `ticker`*, `direction`*, `quantity`*, `orderType`*, `stopPrice`*, `limitPrice`?, `expirationType`?, `expireDate`? | Выставить стоп-заявку |
| `cancel_stop_order` | `accountId`*, `stopOrderId`* | Отменить стоп-заявку |

`*` — обязательный параметр, `?` — опциональный

> **Рабочий процесс:** агент сначала вызывает `get_accounts`, запоминает `accountId` и использует его в последующих запросах.

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

| Переменная | Обязательная | Описание |
|---|---|---|
| `APP_T_INVEST_BASE_URL` | да | URL API T-Invest |
| `APP_T_INVEST_TOKEN` | да | Токен API ([получить](https://developer.tbank.ru)) |
| `APP_T_INVEST_ALLOW_TRADING` | нет | `true` — разрешить торговые операции и переводы. По умолчанию сервер работает в режиме только чтение |

**URL для прода:** `https://invest-public-api.tinkoff.ru/rest/`
**URL для песочницы:** `https://sandbox-invest-public-api.tinkoff.ru/rest/`

## Безопасность

Сервер работает с реальными деньгами через API. Несколько правил, которые сильно снижают риск:

1. **По умолчанию торговля запрещена.** Если `APP_T_INVEST_ALLOW_TRADING` не задан, сервер стартует в режиме только чтение. В этом режиме регистрируются только инструменты на чтение, а 6 операций, которые могут двигать ваши деньги (`post_order`, `cancel_order`, `post_stop_order`, `cancel_stop_order`, `pay_in`, `currency_transfer`), вообще не доступны LLM. Этого достаточно для аналитики, отчётов, мониторинга портфеля.
2. **Включайте торговлю только осознанно через `APP_T_INVEST_ALLOW_TRADING=true`.** Любая торговая операция, которую вызовет LLM, **необратима**. Подтверждение сделок делегировано MCP-клиенту (Claude Desktop спросит вас перед вызовом инструмента) — но это последняя линия защиты, а не первая. Если вы не собираетесь сегодня торговать через ассистента, не давайте ему такую возможность.
3. **Создайте отдельный токен с минимальными правами** на [developer.tbank.ru](https://developer.tbank.ru). Если торговля не нужна — read-only токен. Не используйте основной токен с полными правами «на всякий случай».
4. **Храните токен только в переменных окружения** или секрет-менеджере. Не копируйте его в `claude_desktop_config.json` напрямую, если файл попадает в облачный бэкап / git / shared-машину. На macOS токен из конфига видят все процессы вашего пользователя.
5. **Используйте только HTTPS-URL** для `APP_T_INVEST_BASE_URL`. Сервер откажется стартовать с `http://` — это намеренно.
6. **Никогда не коммитьте `.env`** и не вставляйте токен в issue/PR/чат. Проверьте, что `.gitignore` покрывает `.env` и `*.log`.

Сервер сам не логирует токен и не включает его в ответы MCP, но любая утечка через окружение, конфиг или историю shell остаётся на стороне пользователя.

## Настройка в Claude Desktop

Файл конфигурации: `~/Library/Application Support/Claude/claude_desktop_config.json`

### Через npx

```json
{
  "mcpServers": {
    "t-invest": {
      "command": "npx",
      "args": ["t-invest-mcp-server"],
      "env": {
        "APP_T_INVEST_BASE_URL": "https://invest-public-api.tinkoff.ru/rest/",
        "APP_T_INVEST_TOKEN": "your_token"
      }
    }
  }
}
```

> Добавьте `"APP_T_INVEST_ALLOW_TRADING": "true"` только если осознанно хотите дать LLM возможность размещать ордера и переводить деньги.

### Через Docker

```json
{
  "mcpServers": {
    "t-invest": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "APP_T_INVEST_BASE_URL=https://invest-public-api.tinkoff.ru/rest/",
        "-e", "APP_T_INVEST_TOKEN=your_token",
        "t-invest-mcp-server"
      ]
    }
  }
}
```

## Запуск

### npx

```bash
APP_T_INVEST_BASE_URL=https://invest-public-api.tinkoff.ru/rest/ \
APP_T_INVEST_TOKEN=your_token \
npx t-invest-mcp-server
```

### Docker

```bash
docker build -t t-invest-mcp-server .

docker run -i --rm \
  -e APP_T_INVEST_BASE_URL=https://invest-public-api.tinkoff.ru/rest/ \
  -e APP_T_INVEST_TOKEN=your_token \
  t-invest-mcp-server
```

### Из исходников

```bash
npm install
npm run build
npm start
```

## Дисклеймер

Этот проект — неофициальный инструмент, не связанный с Т-Банком (Тинькофф). Сервер взаимодействует с финансовыми данными и торговыми операциями через публичный API Т-Инвестиций. Пользователи несут полную ответственность за свои действия. Торговля на бирже сопряжена с риском потери средств.

## Лицензия

MIT