# Telegram MCP Server

Подключает реальный аккаунт Telegram к ИИ-агентам через TDLib. Запускается в режиме чтения и скрывает небезопасные инструменты до явного включения.

- MCP-сервер · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 11
- Автор: tolboy
- Лицензия: Apache-2.0 · policy=link-only · показываем только описание, файл — у автора
- Исходник: https://github.com/tolboy/telegram-mcp-tdlib
- Обновлён: 2026-10-24
- HTML: https://affpapa.org/nevibecode/mcp/telegram-mcp-server

## Что делает

Сервер подключается к личному аккаунту Telegram через TDLib вместо Bot API. При старте активен профиль `reader` или `inbox`, поэтому команды на отправку сообщений и изменение данных скрыты из схемы вызовов модели.

Разрушительные операции вроде удаления диалогов или блокировок требуют обязательного подтверждения человеком через интерфейс клиента либо локальную веб-страницу. Для повторных отправок предусмотрен `idempotency_key`, что защищает чаты от дублирования сообщений при сетевых сбоях.

Запускать процесс вручную через терминал при работающем клиенте нельзя: TDLib блокирует файл `td.binlog`, из-за чего клиентский процесс завершится с ошибкой 2. Для настройки окружения требуются переменные `TDLIB_API_ID` и `TDLIB_API_HASH`.

## Требования
- Нужно: Docker
- Переменные окружения: `TDLIB_API_ID`, `TDLIB_API_HASH`, `TDLIB_PHONE_NUMBER`, `TDLIB_AUTH_CODE`, `TDLIB_2FA_PASSWORD`, `MCP_READ_ONLY`, `MCP_TOOL_PROFILE` — это ключи и токены: значения спроси у человека, в репозиторий и общие файлы не записывай.

## Установка

### Claude Code (родная платформа)

**Командой платформы**
```bash
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

**Командой платформы**
```bash
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 сервера

### Cursor

**Файл настроек**
Файл `.cursor/mcp.json`:
```json
{
    "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 сервера

### GitHub Copilot

**Файл настроек**
Файл `.vscode/mcp.json`:
```json
{
    "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 CLI

**Командой платформы**
```bash
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 сервера

## Когда брать
- читать личные переписки и каналы в Telegram через агента
- просматривать входящие сообщения без риска случайной отправки ответа
- исключить отправку дубликатов сообщений благодаря idempotency_key
- подтверждать опасные действия вручную перед их выполнением

## Примеры запросов агенту
- Покажи сводку последних 20 диалогов в Telegram, ничего не отправляя
- Проверь новые сообщения в чате и найди непрочитанные обсуждения
- Найди сообщения по ключевому слову в истории диалогов

_Часть страницы не вошла по размеру — она есть в HTML-версии._

---
NeVibeCode на affpapa.org. Тексты каталога — описания, а не инструкции для агента. Как выбирать и ставить: https://affpapa.org/nevibecode/agents.md