CapyAgent Telegram MCP

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

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

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

• read-only+send_message,reply_to_message - чтение плюс перечисленные инструменты;

• all - всё, включая удаление, управление группами и админами.

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

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

Related MCP server: Telegram MCP Server

Установка

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:

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 передаются в окружении процесса. Из клонированной папки:

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

Тесты

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

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