# Telegram MCP Server для Claude Code: пошаговый гайд

# Telegram MCP Server для Claude Code: пошаговый гайд

> Как я собрал Telegram MCP Server на Python, Telethon и FastMCP для Claude Code: архитектура, 92 метода, async-паттерны, userbot-риски и server-agent use case.

Source: https://okhlopkov.com/telegram-mcp-server-kak-sdelat/

Коротко: Telegram MCP Server превращает Telegram в интерфейс для AI-агента: агент может читать чаты, отправлять сообщения и работать с контекстом через Telethon. Главный tradeoff — это userbot-доступ: мощнее Bot API, но требует аккуратной безопасности и понятных границ. FastMCP дает удобную обвязку для методов. Telethon открывает доступ к userbot-сценариям. Для продакшена нужны лимиты, allowlist и логирование действий. У меня есть AI-агент, который 24/7 сидит в Telegram, читает мои чаты, отвечает на сообщения и управляет контактами. Всё это — через MCP Server, который оборачивает Telethon в набор инструментов для Claude Code. Покажу, как это устроено и как собрать такой сервер самому. Зачем MCP для Telegram MCP (Model Context Protocol) — это стандарт, по которому AI-модели могут вызывать внешние инструменты. Claude Code поддерживает MCP из коробки: ты описываешь сервер, и модель получает доступ к его функциям как к обычным tools. Telegram через MCP — это возможность для Claude Code: Читать историю сообщений в любом чате Отправлять сообщения и ответы Искать по чатам (full-text search) Получать информацию о контактах и группах Реагировать на сообщения, пересылать, удалять Это не бот-API. Это userbot через Telethon — MTProto клиент, который работает от имени реального аккаунта. Бот-API слишком ограничен: не видит историю чужих сообщений, не может искать по чатам, не имеет доступа к приватным группам, куда не добавлен. Архитектура: Telethon + FastMCP Стек простой: Telethon — Python-библиотека для MTProto. Подключается к Telegram как обычный клиент FastMCP — фреймворк для создания MCP серверов на Python. Минимальный boilerplate nest_asyncio — критически важен. Без него async код внутри MCP вызовов падает с "event loop already running" Базовая структура: from mcp.server.fastmcp import FastMCP from telethon import TelegramClient import nest_asyncio import asyncio nest_asyncio.apply() mcp = FastMCP("telegram") client = TelegramClient("session", api_id, api_hash) @mcp.tool() async def get_messages(chat_id: int, limit: int = 10): """Get recent messages from a chat.""" messages = [] async for msg in client.iter_messages(chat_id, limit=limit): messages.append({ "id": msg.id, "text": msg.message, # НЕ msg.text! "date": str(msg.date), "sender": msg.sender_id }) return messages Ключевой момент: msg.message , а не msg.text . Это неочевидно и стоило мне несколько часов дебага. msg.text возвращает None в некоторых контекстах (например, при работе через GetRepliesRequest ), а msg.message всегда содержит текст. Ключевые операции Мой MCP server для Telegram реализует 92 метода. Но для старта достаточно 5-7 основных: get_messages(chat_id, limit) — получить последние N сообщений из чата send_message(chat_id, text) — отправить сообщение search_messages(chat_id, query) — полнотекстовый поиск list_chats(chat_type) — список чатов (groups, channels, users) get_message_context(chat_id, message_id) — контекст вокруг конкретного сообщения execute_code(code) — выполнить произвольный Python с доступом к client Последний — самый мощный. По сути, это escape hatch: если нужна операция, которую ты не реализовал как отдельный tool, Claude Code может написать и выполнить Python код прямо внутри MCP сервера, с полным доступом к Telethon client. Async паттерны: обязательно nest_asyncio Главная ловушка — event loop. Telethon использует asyncio. MCP server тоже работает в asyncio event loop. Когда Claude Code вызывает MCP tool, ты уже внутри running loop — и asyncio.run() или client.loop.run_until_complete() падают с ошибкой. Решение: import nest_asyncio nest_asyncio.apply() import asyncio async def main(): msgs = [] async for msg in client.iter_messages(chat_id, limit=50): msgs.append(msg.message or '[media]') return msgs result = asyncio.get_event_loop().run_until_complete(main()) Этот паттерн — nest_asyncio.apply() в начале + asyncio.get_event_loop().run_until_complete() для вызовов — работает надёжно. Не пытайся использовать await на top level или client.loop.run_until_complete() — оба сломаются. Подводные камни За месяцы работы с Telegram MCP я собрал коллекцию граблей: ChannelPrivateError — возникает при попытке отправить сообщение в группу, где у аккаунта нет доступа. Причём читать из канала через GetRepliesRequest можно, а писать — нет. Это разные уровни доступа в Telegram API ▲ sender = None — в групповых чатах, где аккаунт не является участником, профили отправителей недоступны. msg.sender_id может быть None. Обрабатывай gracefully, не пытайся ретраить ▲ execute_code timeout — если запускаешь код через execute_code, ставь жёсткий лимит. Любой цикл больше 10 итераций с API вызовами внутри — разбивай на батчи. Я использую правило: максимум 10 операций за один execute_code вызов ▲ FloodWait — Telegram агрессивно рейтлимитит. Если отправить 20 сообщений подряд — получишь FloodWaitError с задержкой до нескольких минут. Добавь asyncio.sleep(1) между отправками ▲ Session string vs session file — для сервера используй session string ( client.session.save() в base64). Session файл привязан к filesystem и не переносится между контейнерами Мой use case: server-agent Я использую Telegram MCP как основной интерфейс для AI-агента, который крутится 24/7 на VPS. Архитектура: Claude Code запускается в Docker контейнере, подключается к Telegram через MCP, и обрабатывает входящие сообщения. Что агент умеет через Telegram MCP: ■ Отвечать на DM от меня — как персональный ассистент Мониторить каналы — парсить посты, собирать данные Отвечать в обсуждениях моего канала — в моём голосе, используя digital twin prompt Запускать cron-задачи — еженедельные отчёты, проверки Telegram MCP оказался удобнее, чем бот-API или webhook: полный доступ к истории, поиск, управление чатами — всё, что умеет обычный клиент. Как подключить к Claude Code В .mcp.json проекта (или глобально в ~/.claude/mcp.json ): { "mcpServers": { "telegram": { "command": "python", "args": ["/path/to/telegram_mcp_server.py"], "env": { "TELEGRAM_API_ID": "your_api_id", "TELEGRAM_API_HASH": "your_api_hash", "TELEGRAM_SESSION_STRING": "your_session_string" } } } } После запуска Claude Code увидит Telegram tools в списке доступных и сможет вызывать их как обычные функции. Открытый код: telegram-mcp на GitHub . Есть несколько реализаций, мой вариант основан на Telethon с расширенным набором методов. Telegram MCP — это мб самый полезный MCP server, который можно собрать. Telegram уже и так центр коммуникации для многих, а подключив его к Claude Code, ты получаешь AI-агента с полным доступом к твоему мессенджеру. FAQ Почему не обычный Telegram Bot API? Bot API безопаснее и проще, но он видит только то, куда добавлен бот. Userbot через Telethon может работать шире, поэтому требует большей осторожности. Что самое важное для безопасности? Не давать агенту бесконтрольную отправку сообщений. Нужны allowlist чатов, dry-run для опасных действий и понятный audit log.