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`).

Настройка клиентов

cursor
{
    "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.

claude_desktop_config.json
{
  "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.

Риск: medium Лицензия: MIT ★ 82 058

PraisonAI

Фреймворк агентов PraisonAI с саморефлексией и поддержкой MCP.

Риск: medium Лицензия: MIT ★ 9 327

mcp-atlassian

Поиск, чтение, создание и управление контентом Confluence и Jira, включая Server и Data Center.

Риск: high Лицензия: MIT ★ 6 118

Jitsu

Управление пайплайнами данных Jitsu: направления, потоки, подключения и функции.

Риск: medium Лицензия: MIT ★ 5 132

Источники