Telegram MCP Server — MCP-сервер для Claude Code: обзор и установка
Подключает реальный аккаунт Telegram к ИИ-агентам через TDLib. Запускается в режиме чтения и скрывает небезопасные инструменты до явного включения.
claude mcp add --env TDLIB_API_ID=<TDLIB_API_ID> --env TDLIB_API_HASH=<TDLIB_API_HASH> --env TDLIB_PHONE_NUMBER=<TDLIB_PHONE_NUMBER> --env TDLIB_AUTH_CODE=<TDLIB_AUTH_CODE> --env TDLIB_2FA_PASSWORD=<TDLIB_2FA_PASSWORD> --transport stdio telegram-mcp-server -- docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdioЧто делает Telegram MCP Server
Сервер подключается к личному аккаунту Telegram через TDLib вместо Bot API. При старте активен профиль reader или inbox, поэтому команды на отправку сообщений и изменение данных скрыты из схемы вызовов модели.
Разрушительные операции вроде удаления диалогов или блокировок требуют обязательного подтверждения человеком через интерфейс клиента либо локальную веб-страницу. Для повторных отправок предусмотрен idempotency_key, что защищает чаты от дублирования сообщений при сетевых сбоях.
Запускать процесс вручную через терминал при работающем клиенте нельзя: TDLib блокирует файл td.binlog, из-за чего клиентский процесс завершится с ошибкой 2. Для настройки окружения требуются переменные TDLIB_API_ID и TDLIB_API_HASH.
Какие задачи решает
- читать личные переписки и каналы в Telegram через агента
- просматривать входящие сообщения без риска случайной отправки ответа
- исключить отправку дубликатов сообщений благодаря idempotency_key
- подтверждать опасные действия вручную перед их выполнением
Примеры запросов агенту
- Покажи сводку последних 20 диалогов в Telegram, ничего не отправляя
- Проверь новые сообщения в чате и найди непрочитанные обсуждения
- Найди сообщения по ключевому слову в истории диалогов
Как установить Telegram MCP Server
Командой платформы
claude mcp add --env TDLIB_API_ID=<TDLIB_API_ID> --env TDLIB_API_HASH=<TDLIB_API_HASH> --env TDLIB_PHONE_NUMBER=<TDLIB_PHONE_NUMBER> --env TDLIB_AUTH_CODE=<TDLIB_AUTH_CODE> --env TDLIB_2FA_PASSWORD=<TDLIB_2FA_PASSWORD> --transport stdio telegram-mcp-server -- docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdioВместо <…> подставьте свои значения. Ещё 2 переменные окружения — в README сервера
Командой платформы
codex mcp add telegram-mcp-server --env TDLIB_API_ID=<TDLIB_API_ID> --env TDLIB_API_HASH=<TDLIB_API_HASH> --env TDLIB_PHONE_NUMBER=<TDLIB_PHONE_NUMBER> --env TDLIB_AUTH_CODE=<TDLIB_AUTH_CODE> --env TDLIB_2FA_PASSWORD=<TDLIB_2FA_PASSWORD> -- docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdioВместо <…> подставьте свои значения. Ещё 2 переменные окружения — в README сервера
Файл настроек
{
"mcpServers": {
"telegram-mcp-server": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"TDLIB_API_ID",
"-e",
"TDLIB_API_HASH",
"-e",
"TDLIB_PHONE_NUMBER",
"-e",
"TDLIB_AUTH_CODE",
"-e",
"TDLIB_2FA_PASSWORD",
"ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdio"
],
"env": {
"TDLIB_API_ID": "<TDLIB_API_ID>",
"TDLIB_API_HASH": "<TDLIB_API_HASH>",
"TDLIB_PHONE_NUMBER": "<TDLIB_PHONE_NUMBER>",
"TDLIB_AUTH_CODE": "<TDLIB_AUTH_CODE>",
"TDLIB_2FA_PASSWORD": "<TDLIB_2FA_PASSWORD>"
}
}
}
}Вместо <…> подставьте свои значения. Ещё 2 переменные окружения — в README сервера
Файл настроек
{
"servers": {
"telegram-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"-e",
"TDLIB_API_ID",
"-e",
"TDLIB_API_HASH",
"-e",
"TDLIB_PHONE_NUMBER",
"-e",
"TDLIB_AUTH_CODE",
"-e",
"TDLIB_2FA_PASSWORD",
"ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdio"
],
"env": {
"TDLIB_API_ID": "<TDLIB_API_ID>",
"TDLIB_API_HASH": "<TDLIB_API_HASH>",
"TDLIB_PHONE_NUMBER": "<TDLIB_PHONE_NUMBER>",
"TDLIB_AUTH_CODE": "<TDLIB_AUTH_CODE>",
"TDLIB_2FA_PASSWORD": "<TDLIB_2FA_PASSWORD>"
}
}
}
}Вместо <…> подставьте свои значения. Ещё 2 переменные окружения — в README сервера
Командой платформы
gemini mcp add -e TDLIB_API_ID=<TDLIB_API_ID> -e TDLIB_API_HASH=<TDLIB_API_HASH> -e TDLIB_PHONE_NUMBER=<TDLIB_PHONE_NUMBER> -e TDLIB_AUTH_CODE=<TDLIB_AUTH_CODE> -e TDLIB_2FA_PASSWORD=<TDLIB_2FA_PASSWORD> telegram-mcp-server docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdioВместо <…> подставьте свои значения. Ещё 2 переменные окружения — в README сервера
По шагам, с командами для каждой платформы: Как подключить MCP-сервер: Claude Code, Codex, Cursor, VS Code, Gemini CLI и другие
Вопросы о Telegram MCP Server
Что делает Telegram MCP Server?
Он даёт ИИ-агенту доступ к перепискам личного аккаунта Telegram на базе TDLib. Сервер открывается только на чтение, пряча функции записи до явной настройки профиля.
Как установить Telegram MCP Server в Claude Code?
Выполните команду `claude mcp add --env TDLIB_API_ID=<TDLIB_API_ID> --env TDLIB_API_HASH=<TDLIB_API_HASH> --env TDLIB_PHONE_NUMBER=<TDLIB_PHONE_NUMBER> --env TDLIB_AUTH_CODE=<TDLIB_AUTH_CODE> --env TDLIB_2FA_PASSWORD=<TDLIB_2FA_PASSWORD> --transport stdio telegram-mcp-server -- docker run -i --rm -e TDLIB_API_ID -e TDLIB_API_HASH -e TDLIB_PHONE_NUMBER -e TDLIB_AUTH_CODE -e TDLIB_2FA_PASSWORD ghcr.io/tolboy/telegram-mcp-tdlib:1.17.3-stdio`.
Почему падает процесс при ручном запуске команды serve?
Если запустить сервер в терминале отдельно, процесс заблокирует файл td.binlog. В этот момент клиент не сможет взять блокировку сессии и завершится с кодом 2.
