Metadata-Version: 2.5
Name: t-bank-invest-mcp-read-only
Version: 1.0.0.dev3
Summary: MCP server for reading T-Bank (Tinkoff) investment portfolio data
Project-URL: Homepage, https://github.com/Sicness/t-bank-invest-mcp-read-only
Project-URL: Repository, https://github.com/Sicness/t-bank-invest-mcp-read-only
Project-URL: Issues, https://github.com/Sicness/t-bank-invest-mcp-read-only/issues
Project-URL: Changelog, https://github.com/Sicness/t-bank-invest-mcp-read-only/blob/main/CHANGELOG.md
Author: Anton Balashov
License-Expression: MIT
License-File: LICENSE
Keywords: invest,mcp,model-context-protocol,portfolio,read-only,t-bank,tinkoff
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.11
Requires-Dist: certifi
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]<2,>=1.14.0
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# T-Bank Invest MCP Server (read-only)

[![Tests](https://github.com/Sicness/t-bank-invest-mcp-read-only/actions/workflows/tests.yml/badge.svg)](https://github.com/Sicness/t-bank-invest-mcp-read-only/actions/workflows/tests.yml)
[![PyPI](https://img.shields.io/pypi/v/t-bank-invest-mcp-read-only)](https://pypi.org/project/t-bank-invest-mcp-read-only/)

<!-- mcp-name: io.github.Sicness/t-bank-invest-mcp-read-only -->

MCP-сервер для работы с инвестиционным портфелем Т-Банка (Тинькофф) через AI-ассистентов. Предоставляет **только чтение** — сервер не может совершать сделки, выводить средства или изменять настройки счёта.

## Возможности

- **Портфель и счета** — просмотр счетов, позиций, доходности, маржинальных показателей
- **История операций** — сделки, дивиденды, купоны, налоги, комиссии с фильтрацией и пагинацией
- **Поиск инструментов** — по тикеру, названию, ISIN, FIGI; детальная информация по акциям, облигациям, ETF, валютам, фьючерсам
- **Рыночные данные** — свечи (OHLCV), стакан заявок, статус торгов, цены закрытия
- **Аналитика** — технический анализ (SMA, EMA, RSI, MACD, Bollinger Bands), фундаментальные показатели (P/E, EPS, ROE), консенсус-прогнозы аналитиков, а также `get_stock_snapshot` — сводка по тикеру одним вызовом (фундаментал + изменение цены + консенсус)
- **Облигации** — купонный календарь, НКД, события (амортизации, оферты)
- **Дивиденды** — история и предстоящие выплаты

## Требования

- [uv](https://docs.astral.sh/uv/getting-started/installation/) — запускает сервер одной командой: сам подбирает Python 3.11+ и ставит зависимости в изолированное окружение
- Токен T-Invest API — выпустить на [tbank.ru/invest/settings/api](https://www.tbank.ru/invest/settings/api/)

### Какой токен выпускать

Выпускайте токен **только для чтения** (readonly). Сервер вызывает только методы чтения, права на сделки ему не нужны, а с таким токеном торговые поручения невозможны уже на стороне Т-Банка — это вторая линия защиты помимо кода сервера. Токен можно дополнительно ограничить одним счётом.

MCP-клиенты хранят токен в своей конфигурации открытым текстом — ещё одна причина не давать ему прав на сделки.

## Подключение

Сервер опубликован на [PyPI](https://pypi.org/project/t-bank-invest-mcp-read-only/): клонировать репозиторий не нужно, `uvx` скачает и запустит его сам. Токен передаётся через переменную окружения `TBANK_INVEST_TOKEN` в конфигурации MCP-клиента.

### Claude Code

```bash
claude mcp add t-bank-invest -e TBANK_INVEST_TOKEN=your_token_here -- uvx t-bank-invest-mcp-read-only
```

По умолчанию сервер подключается только к текущему проекту; чтобы он был доступен во всех проектах, добавьте `--scope user`. С `--scope project` конфигурация вместе с токеном записывается в `.mcp.json` в корне проекта — не коммитьте этот файл.

### Claude Desktop

Добавьте сервер в `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`) и перезапустите приложение:

```json
{
  "mcpServers": {
    "t-bank-invest": {
      "command": "uvx",
      "args": ["t-bank-invest-mcp-read-only"],
      "env": {
        "TBANK_INVEST_TOKEN": "your_token_here"
      }
    }
  }
}
```

Если Claude Desktop не находит `uvx`, укажите в `command` полный путь к нему (его покажет `which uvx`).

### Другие MCP-клиенты

Сервер работает по stdio. В любом клиенте укажите ту же команду, те же аргументы и переменную окружения, что в примере для Claude Desktop.

Сервер также есть в [реестре MCP-серверов](https://registry.modelcontextprotocol.io/) под именем `io.github.Sicness/t-bank-invest-mcp-read-only`.

### Конкретная версия

`uvx` берёт последнюю версию с PyPI и обновляется сам. Чтобы закрепить версию, укажите её после имени — `t-bank-invest-mcp-read-only@1.0.0`; что менялось от версии к версии — в [истории изменений](https://github.com/Sicness/t-bank-invest-mcp-read-only/blob/main/CHANGELOG.md).

Ещё не выпущенное состояние ветки `main`: `uvx --from git+https://github.com/Sicness/t-bank-invest-mcp-read-only t-bank-invest-mcp-read-only`.

### Установка из исходников

Для разработки или если `uv` не подходит:

```bash
git clone https://github.com/Sicness/t-bank-invest-mcp-read-only.git
cd t-bank-invest-mcp-read-only
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[test]"
```

В конфигурации MCP-клиента тогда указывается полный путь к команде: `/path/to/t-bank-invest-mcp-read-only/.venv/bin/t-bank-invest-mcp-read-only`, без `args`.

### Запуск напрямую

Сервер **не** загружает `.env` файл — переменную нужно экспортировать в shell:

```bash
export TBANK_INVEST_TOKEN=your_token_here
uvx t-bank-invest-mcp-read-only
```

Из установленного окружения то же самое делает команда `t-bank-invest-mcp-read-only` или `python -m tbank_invest_mcp`.

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

### Счета и пользователь
| Инструмент | Описание |
|---|---|
| `get_accounts` | Список инвестиционных счетов |
| `get_user_info` | Тариф, статус квал. инвестора, уровень риска |
| `get_margin_attributes` | Маржинальные показатели счёта |

### Портфель и позиции
| Инструмент | Описание |
|---|---|
| `get_portfolio` | Полный портфель с ценами и доходностью; у позиций опущены нулевые поля |
| `get_positions` | Балансы позиций без расчёта цен |
| `get_withdraw_limits` | Доступные средства для вывода |

### Операции
| Инструмент | Описание |
|---|---|
| `get_operations` | История операций за период |
| `get_operations_by_cursor` | История операций с пагинацией и расширенными фильтрами |

### Инструменты
| Инструмент | Описание |
|---|---|
| `find_instrument` | Поиск по тикеру, названию, ISIN, FIGI. По умолчанию — только торгуемые через API бумаги, не больше 20; есть фильтр по типу инструмента |
| `get_instrument_by` | Детальная информация по идентификатору |
| `get_bond_by` | Информация об облигации |
| `get_share_by` | Информация об акции |
| `get_etf_by` | Информация об ETF/фонде |
| `get_currency_by` | Информация о валютном инструменте |
| `get_future_by` | Информация о фьючерсном контракте |
| `get_bond_coupons` | Купонный календарь облигации |
| `get_bond_events` | События облигации: купоны, оферты, погашение, конвертации; фильтр по типу и периоду |
| `get_dividends` | История и будущие дивиденды |
| `get_accrued_interests` | НКД (накопленный купонный доход) |
| `get_asset_fundamentals` | P/E, EPS, ROE, капитализация |
| `get_consensus_forecasts` | Консенсус-прогноз аналитиков по одному инструменту (сканирует страницы и фильтрует по `instrument_id` — UID инструмента или актива, т.к. сам API не умеет фильтровать на своей стороне) |
| `get_forecast_by` | Прогнозы инвестдомов по инструменту |
| `get_asset_reports` | Даты отчётностей эмитента |
| `get_stock_snapshot` | Сводка по акции одним вызовом: резолвит тикер → UID → UID актива и объединяет фундаментал, изменение цены за N торговых сессий и консенсус-прогноз |
| `get_favorites` | Избранные инструменты пользователя |
| `get_trading_schedules` | Расписание торгов бирж |

### Рыночные данные
| Инструмент | Описание |
|---|---|
| `get_candles` | Исторические свечи (OHLCV) строками `[время, open, high, low, close, объём, покупки, продажи]` |
| `get_last_prices` | Последние цены сделок |
| `get_close_prices` | Цены закрытия предыдущей сессии |
| `get_order_book` | Стакан заявок (bids/asks) |
| `get_trading_status` | Текущий статус торгов |
| `get_tech_analysis` | Технические индикаторы (SMA, EMA, RSI, MACD, BB) |

### Заявки
| Инструмент | Описание |
|---|---|
| `get_orders` | Активные заявки на счёте |
| `get_order_state` | Статус конкретной заявки |

### Списки инструментов
| Инструмент | Описание |
|---|---|
| `list_shares` | Полный справочник акций — около 2 МБ |
| `list_bonds` | Полный справочник облигаций — около 2,4 МБ |
| `list_etfs` | Полный справочник ETF/фондов — около 300 КБ |
| `list_currencies` | Все валютные инструменты — около 13 КБ |
| `list_futures` | Полный справочник фьючерсов — около 700 КБ |

Справочники, кроме валютного, — выгрузки для скриптов: в контекст модели они не помещаются, клиент сохранит такой ответ в файл или отклонит его. Чтобы найти бумагу, используйте `find_instrument`.

## Формат данных

Ответы рассчитаны на то, что их читает модель, поэтому сервер не пересылает ответ API как есть:

- **Цены и суммы — обычные числа**, а не пары `units`/`nano`. Валюта указана один раз, в поле `currency` того же объекта; сумма в другой валюте записана как `{"value": ..., "currency": ...}`.
- **В списках позиций, операций и событий облигаций опущены нулевые и пустые поля.** Отсутствие поля означает ноль, «нет» или пусто.
- **Инструмент можно назвать как угодно**: тикером, FIGI, ISIN или UID — в любом параметре, который принимает инструмент. Если под одним тикером торгуются разные бумаги (`T` — это и Т-Технологии, и AT&T), сервер попросит уточнить в виде `ТИКЕР_КЛАСС`, например `T_TQBR`. По названию ищет `find_instrument`.
- **Даты — в UTC.** Дата без времени в `to_date` включает весь этот день.

## Примеры запросов к ассистенту

- «Покажи мой портфель и общую доходность»
- «Какие дивиденды я получил за последний год?»
- «Найди облигации Газпрома и покажи купонный календарь»
- «Сравни P/E Сбера и ВТБ»
- «Дай сводку по SBER: фундаментал, динамика цены, консенсус аналитиков»
- «Построй RSI для AAPL за последние 3 месяца»
- «Какие у меня активные заявки?»

## Лицензия

[MIT](LICENSE)
