# CapyAgent Telegram MCP

Подключает личный аккаунт Telegram к CapyAgent, Codex, Cursor и любым другим MCP-клиентам. Около 80 инструментов: чтение и поиск по чатам, сводки непрочитанного, отправка и правка сообщений, файлы, голосовые с расшифровкой, группы и каналы, несколько аккаунтов сразу.

## Главное про безопасность

По умолчанию сервер отдаёт агенту только инструменты чтения (`TELEGRAM_EXPOSED_TOOLS=read-only`). Запись включается явно:

- `read-only+send_message,reply_to_message` - чтение плюс перечисленные инструменты;
- `all` - всё, включая удаление, управление группами и админами.

Дополнительно можно ограничить чаты: `TELEGRAM_ALLOWED_CHAT_IDS=123,-100456`.

Одну Telethon-сессию нельзя держать двумя процессами одновременно, она ломается. Под этот сервер нужна отдельная сессия.

## Установка

```bash
git clone https://github.com/smolnikov-k/capy-tg-mcp && cd capy-tg-mcp
uv sync
cp .env.example .env   # вписать TELEGRAM_API_ID и TELEGRAM_API_HASH с my.telegram.org
uv run capy-tg-mcp-session   # вход по номеру и коду, выдаст строку сессии
```

Строку сессии положить в `.env` как `TELEGRAM_SESSION_STRING`. Чтобы Телеграм не видел «новое устройство» при каждом подключении, задать `TELEGRAM_DEVICE_MODEL`, `TELEGRAM_SYSTEM_VERSION`, `TELEGRAM_APP_VERSION`.

## Подключение к MCP-клиенту

Сервер работает по stdio. Без клонирования, прямо с GitHub:

```bash
uvx --from git+https://github.com/smolnikov-k/capy-tg-mcp@v1.0.0 capy-tg-mcp
```

Переменные TELEGRAM_API_ID, TELEGRAM_API_HASH и TELEGRAM_SESSION_STRING передаются в окружении процесса. Из клонированной папки:

```bash
uv --directory /path/to/capy-tg-mcp run main.py
```

## Тесты

```bash
uv sync --group dev && uv run pytest -q
```

Полная документация по всем инструментам и переменным: [docs/README.upstream.md](docs/README.upstream.md).