telegram

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

Daniil Okhlopkov

• 3 min read
Telegram MCP Server для Claude Code: пошаговый гайд

У меня есть 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-агента с полным доступом к твоему мессенджеру.

Подписывайся на Telegram — @danokhlopkov