Telegram MCP Server
Telegram MCP Server — MCP-сервер сообщества (автор — tolboy). Локальный сервер Telegram на TDLib: 126 инструментов, изоляция аккаунтов и защитные ограничения. Ставится через Docker. Лицензия Apache-2.0.
Опубликовано 13.11.2026 · Обновлено 13.11.2026 · Проверено 13.11.2026
Кратко о сервере
- Разработчик
- tolboy
- Лицензия
- Apache-2.0
- Транспорт
- stdio, streamable_http
- Авторизация
- other
- ОС
- Не указана
- Языки
- kotlin
Уровень риска: high
Доступ к личному аккаунту Telegram через TDLib. По умолчанию только чтение; при включении записи оставляйте подтверждение человеком (`MCP_DESTRUCTIVE_APPROVAL=auto`).
Настройка клиентов
{
"code": "{\n \"mcpServers\": {\n \"telegram\": {\n \"command\": \"telegram-mcp\",\n \"args\": [\"serve\", \"--transport\", \"stdio\"],\n \"env\": {\n \"TDLIB_API_ID\": \"123456\",\n \"TDLIB_API_HASH_FILE\": \"/absolute/path/to/telegram-api-hash\",\n \"MCP_TOOL_PROFILE\": \"inbox\",\n \"MCP_READ_ONLY\": \"true\"\n }\n }\n }\n}",
"file": "~/.cursor/mcp.json",
"lang": "json",
"notes": "Тот же блок; README указывает ~/.cursor/mcp.json",
"verified": "docs"
}
Что умеет
Telegram MCP Server (telegram-mcp-tdlib) даёт ИИ-агенту доступ к настоящему аккаунту Telegram, а не только к Bot API. Сервер построен на TDLib (через tdlight-java), работает локально по STDIO для настольных клиентов или по Streamable HTTP на /mcp для управляемых развёртываний.
- Безопасный старт: сервер запускается в режиме только для чтения с небольшим профилем
inbox/reader. Инструменты записи и расходующие квоту скрыты от модели, а не просто заблокированы, пока вы их не включите. - Подтверждение человеком: разрушительные инструменты сначала спрашивают человека — через MCP-клиент, если он поддерживает elicitation, или через одноразовую локальную страницу, которую поднимает сервер. Вопрос и ответ проходят вне хода модели.
- Повтор отправки без дублей:
idempotency_keyпревращает потерянный ответ в сохранённую квитанцию, а неподтверждённая отправка помечается какUNKNOWNи не повторяется молча. - Несколько аккаунтов: у каждого своя сессия, обязательный выбор и свои ключи API, чтение не смешивает аккаунты.
- Без установки JDK: готовые сборки для Windows, Linux x64/ARM64 и macOS на Apple silicon с контрольными суммами, SBOM и подписанными образами контейнеров.
Профили инструментов: reader, inbox, community-admin, all.
Кому подойдёт
- Тем, кто хочет сводки по своим чатам: агент читает последние разговоры и пересказывает их, ничего не меняя.
- Администраторам сообществ: профиль
community-adminс подтверждением опасных действий человеком. - Командам, которым нужен общий сервис: развёртывание по HTTP в Docker с ключом API или OAuth.
Похожие серверы — в категории коммуникации.
Установка
Для первого запуска по возможности используйте тестовый аккаунт. Установка на macOS (Apple silicon) или Linux через Homebrew:
brew install --formula https://github.com/tolboy/telegram-mcp-tdlib/releases/latest/download/telegram-mcp.rbНа Windows доступна установка через Scoop. Затем войдите по QR-коду и проверьте сессию:
telegram-mcp auth --method qr
telegram-mcp session doctorНе запускайте serve --transport stdio вручную для пробы: при STDIO сервер запускает клиент, а копия в терминале занимает сессию TDLib, и копия клиента завершится с кодом 2. Запись для клиента лучше сгенерировать командой telegram-mcp config --client claude (также claude-code, cursor, vscode, codex).
Подключение к клиентам
Конфиг приведён дословно из README, это пример сгенерированной записи. Подставьте свои TDLIB_API_ID и путь к файлу с хешем API. Общий порядок — в инструкции как подключить MCP.
{
"mcpServers": {
"telegram": {
"command": "telegram-mcp",
"args": ["serve", "--transport", "stdio"],
"env": {
"TDLIB_API_ID": "123456",
"TDLIB_API_HASH_FILE": "/absolute/path/to/telegram-api-hash",
"MCP_TOOL_PROFILE": "inbox",
"MCP_READ_ONLY": "true"
}
}
}
}После правки конфига Claude Desktop нужно полностью закрыть из трея и запустить снова. В VS Code ключ верхнего уровня называется servers и нужен явный "type": "stdio".
Проверка
Начните с запроса, который ничего не может изменить: «Перескажи мои последние 20 разговоров. Ничего не отправляй и не меняй». В режиме чтения инструментов записи в списке нет совсем.
Примеры задач
Перескажи мои последние 20 разговоров. Ничего не отправляй и не меняй.Покажи последние посты публичного канала @telegram.Риски
Сервер работает с вашим личным аккаунтом Telegram через TDLib. После включения записи агент может отправлять сообщения и выполнять действия администратора, вплоть до банов в сообществах.
Что встроено: по умолчанию режим только для чтения. Если включить MCP_READ_ONLY=false, задайте MCP_DESTRUCTIVE_APPROVAL=auto (или elicitation / loopback). Сервер не запустится, если запись включена, а подтверждение выключено, потому что "confirmed": true модель может выставить сама. Флаг MCP_ALLOW_MODEL_CONFIRMED_WRITES=true снимает эту защиту, не включайте его без необходимости. Хеш API храните в файле, а не в конфиге. Лицензия — Apache-2.0.
Частые вопросы
Нужно ли ставить Java?
Нет. Готовые сборки включают среду выполнения, JDK, Gradle, Python и Node.js не нужны.
Почему клиент не видит инструменты отправки?
По умолчанию включены режим чтения и профиль reader. Запись включается через --writes вместе с профилем inbox, community-admin или all.
Можно ли подключить сервер к Claude Desktop по HTTP?
Claude Desktop не читает удалённые серверы из claude_desktop_config.json. Для удалённого подключения нужен коннектор в настройках и HTTPS с MCP_AUTH_MODE=oauth.
Основы протокола — на странице что такое MCP-сервер.
Похожие MCP-серверы
Ruflo
Команды и рои агентов, память и хуки для Claude Code и Codex.
PraisonAI
Фреймворк агентов PraisonAI с саморефлексией и поддержкой MCP.
mcp-atlassian
Поиск, чтение, создание и управление контентом Confluence и Jira, включая Server и Data Center.
Jitsu
Управление пайплайнами данных Jitsu: направления, потоки, подключения и функции.