Metadata-Version: 2.4
Name: sber-unofficial-sdk
Version: 0.6.1
Summary: Unofficial async SDK for observed SberBank Online web endpoints
License-Expression: MIT
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: certifi>=2025.1.31
Requires-Dist: curl-cffi<0.16,>=0.15.0
Requires-Dist: tzdata
Dynamic: license-file

<p align="center"><img src="docs/mcp/img/banner.svg" alt="SBER MCP" width="640"></p>

<h1 align="center">sber-mcp</h1>

<p align="center">
  Неофициальный <b>MCP-сервер</b> и async <b>SDK</b> для СберБанк Онлайн:
  вход, чтение продуктов и операций, перевод между своими продуктами —
  <b>напрямую, client&nbsp;↔&nbsp;Сбербанк</b>.
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT"></a>
  <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+">
  <img src="https://img.shields.io/badge/MCP-server-21A038.svg" alt="MCP server">
  <a href="https://github.com/ex3lite/sber-mcp/actions/workflows/ci.yml"><img src="https://github.com/ex3lite/sber-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
</p>

<p align="center">
  Документация: <a href="docs/mcp/README.ru.md"><b>RU</b></a> ·
  <a href="docs/mcp/README.en.md">EN</a> ·
  <a href="docs/mcp/README.zh.md">中文</a>
</p>

> **Неофициальный проект.** Не связан с ПАО Сбербанк. Использование может нарушать
> условия сервиса и привести к блокировке аккаунта; работает с реальными деньгами и
> учётными данными. Никаких гарантий и никакой ответственности —
> [DISCLAIMER.md](DISCLAIMER.md) · [LICENSE](LICENSE).

Агент отвечает на вопрос пользователя, вызвав инструмент MCP:

<p align="center"><img src="docs/mcp/img/claude-chat.svg" alt="Агент отвечает через MCP" width="720"></p>

## Что это

Один пакет — **два равноправных способа** использования; оба работают прямыми
HTTP-запросами, без Chrome, WebDriver и HAR:

- **MCP-сервер** — дайте агенту (Claude, Codex, Cursor) доступ к СберБанк Онлайн:
  чтение продуктов и операций, переводы между своими продуктами с явным
  подтверждением человеком. Быстрый старт и подключение — ниже.
- **Async SDK / CLI** — те же возможности прямо в вашем Python-коде или из
  терминала, **без агента и без MCP** (ставится только с `certifi`+`curl-cffi`).
  См. [«Использовать как SDK»](#использовать-как-sdk-или-cli-без-агента) и
  справочник [docs/SDK.ru.md](docs/SDK.ru.md) · [SDK (EN)](docs/SDK.en.md).

- **Прямо client ↔ Сбербанк.** Никаких сторонних сервисов, прокси или облаков в
  цепочке — трафик идёт с вашей машины напрямую на сервера Сбербанка. Данные не
  проходят через инфраструктуру проекта, потому что её нет.
- **Секреты никогда не проходят через агента.** Ни один инструмент не принимает и
  не возвращает логин, пароль, PIN, OTP, deviceprint, cookie или токен. Разовые
  секреты человек записывает в файл `0600`, сервер читает его и удаляет до сетевого
  вызова. Подробно — [док MCP §1](docs/mcp/README.ru.md).
- **Агент не управляет сессиями.** Логин один раз — дальше `sber_products()` и
  прочее без `session_id`; активную сессию держит сервер.
- **Переводы под контролем человека.** `prepare` рассчитывает, `confirm` исполняет
  только после явного «да»; токен прожигается до сети, повтор не отправляет деньги дважды.

## Быстрый старт

**1. Установка** (команда `sber-unofficial-mcp`):
```bash
uv tool install sber-unofficial-mcp     # или: pipx install sber-unofficial-mcp
```

**2. Вход одной командой.** Интерактивно (скрытым вводом) спросит логин, пароль,
SMS-код и новый PIN, сам сгенерирует device-отпечаток, сохранит профиль в `0600`.
Ни кук, ни HAR, ни ручного редактирования файлов:
```bash
sber-unofficial-mcp login
sber-unofficial-mcp status      # проверить, что профиль сохранён
```

**3. Подключите к агенту** (см. ниже). Дальше сервер входит сам по сохранённому профилю.

> `sber_transfer_confirm` двигает реальные деньги. **Не** добавляйте её в авто-разрешения.

## Подключение агента

<details open>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add sber -- sber-unofficial-mcp
```
</details>

<details>
<summary><b>Claude Desktop</b> — <code>claude_desktop_config.json</code></summary>

```json
{
  "mcpServers": {
    "sber": { "command": "sber-unofficial-mcp" }
  }
}
```
</details>

<details>
<summary><b>Codex</b> — <code>~/.codex/config.toml</code></summary>

```toml
[mcp_servers.sber]
command = "sber-unofficial-mcp"
```
</details>

<details>
<summary><b>Cursor</b> — <code>~/.cursor/mcp.json</code></summary>

```json
{
  "mcpServers": {
    "sber": { "command": "sber-unofficial-mcp" }
  }
}
```
</details>

## Как это выглядит

<p align="center"><img src="docs/mcp/img/login.svg" alt="Вход одной командой" width="720"></p>
<p align="center"><img src="docs/mcp/img/status.svg" alt="Статус профиля" width="520"></p>

## Инструменты

14 инструментов: `sber_setup_status`, `sber_auth_start/continue/resend_otp`,
`sber_session_info/close`, `sber_products`, `sber_operations`,
`sber_operations_page`, `sber_card_rename`, `sber_transfer_start/prepare/confirm`,
`sber_transfer_resolve_uncertain`. Полный справочник, конверт результата и
`next_action`, runbook для агента — в [документации MCP](docs/mcp/README.ru.md).

## Использовать как SDK или CLI (без агента)

MCP-сервер — тонкая обёртка над `sber_unofficial`, самостоятельным async SDK
(SRP-логин, RSA-OAEP шифрование PIN, двухфазный перевод, PIN-релогин без браузера).
SDK **не тянет** зависимости MCP — ставится с одним `certifi`+`curl-cffi`:

```bash
pip install sber-unofficial-sdk         # чистый SDK (без mcp/rich/questionary)
```

**Пайплайн целиком в коде — без CLI и без браузера.** Deviceprint генерируется
самим SDK. Шаг 1 — первый вход, один раз (полный пример: [examples/first_login.py](examples/first_login.py)):

```python
from sber_unofficial import (AsyncPrimaryAuth, PinOtpRequired,
                             generate_deviceprint, generate_antifraud_deviceprint)

dp = generate_deviceprint()                                    # без браузера
auth = AsyncPrimaryAuth.new(deviceprint=dp,
                            antifraud_deviceprint=generate_antifraud_deviceprint(dp))
async with auth:
    try:
        bundle = await auth.login(login, password, store_login=True)
    except PinOtpRequired:                                     # Сбер прислал SMS
        bundle = await auth.confirm_otp(sms_code)
    if bundle is None:                                         # нужен новый PIN
        bundle = await auth.create_pin("12345")
    bundle.save("profile.json")                                # атомарно, mode 0600
```

Шаг 2 — дальше просто читаете по PIN (пример: [examples/quickstart.py](examples/quickstart.py)):

```python
from sber_unofficial import AsyncSberClient

async with await AsyncSberClient.from_pin_profile("profile.json", pin="12345") as sber:
    portfolio = await sber.portfolio()                         # карты + счета одним запросом
    for card in portfolio.cards:
        print(card.name, card.last4, card.balance)             # Money(amount, currency)
    for op in await sber.operations.list(limit=20):
        print(op.date, op.amount, op.description)
```

**Опционально** — если удобнее терминал, у SDK есть свой CLI без агента:
`sber-unofficial enroll` → `sber-unofficial balances/operations` (см. [docs/SDK.ru.md](docs/SDK.ru.md)).

Полный справочник (конструкторы, авторизация, сущности, ошибки, переводы, CLI) —
[docs/SDK.ru.md](docs/SDK.ru.md) · [SDK (EN)](docs/SDK.en.md); детали авторизации
и доказательства — [AUTHENTICATION.md](AUTHENTICATION.md).

## Безопасность и вклад

- Модель защиты секретов и что именно её обеспечивает — [док MCP §1 и §8](docs/mcp/README.ru.md).
- Нашли уязвимость — [SECURITY.md](SECURITY.md) (не через публичный issue).
- PR и issue приветствуются — [CONTRIBUTING.md](CONTRIBUTING.md). Главное правило:
  **никогда не коммитить реальные креды, куки, deviceprint, сессии, HAR и балансы.**

## Лицензия

[MIT](LICENSE). Полный отказ от ответственности — [DISCLAIMER.md](DISCLAIMER.md).
Неофициальный проект, не связан с ПАО Сбербанк; вся ответственность за
использование — на пользователе.
