Telegram MCP

chigwell/telegram-mcp· Проверено 12.11.2026· 2 тыс.на GitHub

Подключает агента к вашему аккаунту Telegram через Telethon: читать чаты, искать по истории, отправлять и редактировать сообщения, управлять группами, контактами, папками и медиа. Больше 80 инструментов.

Как подключить

Что сделать до подключения

Python 3.10 или новее и uv

Копия репозитория: git clone https://github.com/chigwell/telegram-mcp.git и uv sync

Строка сессии: uv run session_string_generator.py, вход по QR-коду или по номеру телефона

TELEGRAM_API_ID, TELEGRAM_API_HASH

на my.telegram.org/apps

TELEGRAM_SESSION_STRING

выдаёт скрипт session_string_generator.py из репозитория; строка даёт доступ ко всему аккаунту

Конфиг для вашего клиента

Команда в терминале, в папке проекта. Флаг --scope user подключит сервер для всех проектов. Подробно о Claude Code

claude mcp add --env 'TELEGRAM_API_ID=<api_id>' --env 'TELEGRAM_API_HASH=<api_hash>' --env 'TELEGRAM_SESSION_STRING=<строка сессии>' --transport stdio telegram \
  -- uv --directory /full/path/to/telegram-mcp run main.py

Проверка: claude mcp list показывает статус рядом с каждым сервером: ✔ Connected, ! Needs authentication или ✘ Failed to connect. Внутри сессии то же видно по команде /mcp.

Файл ~/.codex/config.toml или .codex/config.toml в доверенном проекте. Можно и командой codex mcp add. Подробно о Codex

[mcp_servers.telegram]
command = "uv"
args = ["--directory", "/full/path/to/telegram-mcp", "run", "main.py"]

[mcp_servers.telegram.env]
TELEGRAM_API_ID = "<api_id>"
TELEGRAM_API_HASH = "<api_hash>"
TELEGRAM_SESSION_STRING = "<строка сессии>"

Проверка: В интерфейсе codex введите /mcp: появится список активных серверов. Из терминала то же покажет codex mcp list.

Файл ~/.cursor/mcp.json для всех проектов или .cursor/mcp.json в папке проекта. Подробно о Cursor

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["--directory", "/full/path/to/telegram-mcp", "run", "main.py"],
      "env": {
        "TELEGRAM_API_ID": "<api_id>",
        "TELEGRAM_API_HASH": "<api_hash>",
        "TELEGRAM_SESSION_STRING": "<строка сессии>"
      }
    }
  }
}

Проверка: Откройте Customize в боковой панели: там список серверов с переключателями. Ошибки подключения смотрите в панели Output (Cmd+Shift+U), пункт MCP Logs в выпадающем списке.

Файл .mcp.json в корне проекта или ~/.copilot/mcp-config.json для всех проектов. Подробно о VS Code

{
  "mcpServers": {
    "telegram": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/full/path/to/telegram-mcp", "run", "main.py"],
      "env": {
        "TELEGRAM_API_ID": "<api_id>",
        "TELEGRAM_API_HASH": "<api_hash>",
        "TELEGRAM_SESSION_STRING": "<строка сессии>"
      }
    }
  }
}

Проверка: Попросите Copilot выполнить безобидную задачу через сервер и раскройте вызов инструмента в чате. Одна запись в конфиге подключение не подтверждает.

Файл ~/.qwen/settings.json или .qwen/settings.json в проекте. Подробно о Qwen Code

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["--directory", "/full/path/to/telegram-mcp", "run", "main.py"],
      "env": {
        "TELEGRAM_API_ID": "<api_id>",
        "TELEGRAM_API_HASH": "<api_hash>",
        "TELEGRAM_SESSION_STRING": "<строка сессии>"
      }
    }
  }
}

Проверка: Запустите qwen и введите /mcp: откроется окно управления серверами. Из терминала статус покажет qwen mcp list.

Файл ~/.gemini/settings.json или .gemini/settings.json в проекте. Подробно о Gemini CLI

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["--directory", "/full/path/to/telegram-mcp", "run", "main.py"],
      "env": {
        "TELEGRAM_API_ID": "<api_id>",
        "TELEGRAM_API_HASH": "<api_hash>",
        "TELEGRAM_SESSION_STRING": "<строка сессии>"
      }
    }
  }
}

Проверка: gemini mcp list показывает каждый сервер, его настройки и статус Connected или Disconnected. В сессии /mcp выводит CONNECTED, CONNECTING или DISCONNECTED и список инструментов.

Файл opencode.json в папке проекта или ~/.config/opencode/opencode.json. Подробно о OpenCode

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "telegram": {
        "type": "local",
        "command": ["uv", "--directory", "/full/path/to/telegram-mcp", "run", "main.py"],
        "environment": {
          "TELEGRAM_API_ID": "<api_id>",
          "TELEGRAM_API_HASH": "<api_hash>",
          "TELEGRAM_SESSION_STRING": "<строка сессии>"
        }
      }
    }
  }
}

Проверка: opencode mcp list показывает состояние каждого сервера, подключённый выглядит как ✓ context7 connected. Внутри OpenCode то же видно в /mcps.

Настройки → Разработчик → Изменить конфиг: файл claude_desktop_config.json. После правки перезапустите приложение. Подробно о Claude Desktop

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["--directory", "/full/path/to/telegram-mcp", "run", "main.py"],
      "env": {
        "TELEGRAM_API_ID": "<api_id>",
        "TELEGRAM_API_HASH": "<api_hash>",
        "TELEGRAM_SESSION_STRING": "<строка сессии>"
      }
    }
  }
}

Проверка: Нажмите «Add files, connectors, and more /» в левом нижнем углу поля ввода, наведите на Connectors и откройте Manage connectors. Выберите сервер, чтобы увидеть его инструменты.

Вкладка Program → Install → Edit mcp.json. Подробно о LM Studio

{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": ["--directory", "/full/path/to/telegram-mcp", "run", "main.py"],
      "env": {
        "TELEGRAM_API_ID": "<api_id>",
        "TELEGRAM_API_HASH": "<api_hash>",
        "TELEGRAM_SESSION_STRING": "<строка сессии>"
      }
    }
  }
}

Проверка: Попросите модель в чате выполнить задачу через инструмент сервера. Через API сервер из mcp.json вызывают по id в integrations, например mcp/playwright.

Инструменты сервера

list_chatsперечисляет чаты

get_historyчитает историю чата

search_messagesищет сообщения в чате

search_globalищет по всем чатам

get_message_contextпоказывает сообщения вокруг

export_unread_messagesвыгружает непрочитанные в JSON

export_chat_historyвыгружает историю чата в JSON

send_messageотправляет сообщение

reply_to_messageотвечает на сообщение

edit_messageправит сообщение

send_fileотправляет файл

transcribe_voiceрасшифровывает голосовое

create_pollсоздаёт опрос

press_inline_buttonнажимает кнопку бота

invite_to_groupприглашает в группу

promote_adminназначает администратора

resolve_phoneнаходит пользователя по номеру

set_contact_aliasзапоминает, как вы зовёте контакт

get_draftsпоказывает черновики

wait_for_new_messageждёт нового сообщения

Что попросить агента

«Перескажи мои непрочитанные в Telegram, коротко и по чатам»Агент вызовет list_chats с отбором непрочитанных и get_history по каждому чату, отметки о прочтении не тронет

«<Имя> спросила о сроке сдачи в чате <@чат>. Набросай вежливый ответ, что успеваем к четвергу, но не отправляй»Агент вызовет get_message_context вокруг её сообщения и сохранит ответ черновиком в Telegram

«Найди в чате <@чат> обсуждение «<фраза>» и перескажи, чем закончилось»Агент вызовет search_messages и get_message_context вокруг найденных сообщений

«Расшифруй последнее голосовое от <контакт>»Агент найдёт сообщение через get_history и вызовет transcribe_voice

«Выгрузи историю чата <название> за этот месяц в JSON»Агент вызовет export_chat_history

Для каких задач

Пересказать непрочитанные сообщения и выделить срочные просьбы

Набросать ответы, ничего не отправляя

Найти обсуждение в истории чата и собрать вокруг него контекст

Расшифровать голосовые и кружки в текст

Выгрузить историю чата в структурированный JSON

Управлять группой: пригласить участников, назначить админов, включить медленный режим

Ограничения

Сервер действует от имени вашего аккаунта: строка сессии открывает к нему полный доступ, хранить её нужно как пароль

Не ставьте сервер через uvx telegram-mcp или pip install telegram-mcp: это имя на PyPI занято чужим проектом, туда утекут ключи

По умолчанию агент видит все чаты; ограничить их можно списком TELEGRAM_ALLOWED_CHAT_IDS

Расшифровка голосовых по умолчанию отправляет запись в Groq и требует GROQ_API_KEY; расширенное форматирование сообщений требует Telegram Premium

Если не работает

Сервер пишет No Telegram session configured

Задайте TELEGRAM_SESSION_STRING или TELEGRAM_SESSION_NAME, для нескольких аккаунтов — переменные с суффиксами.

Ошибка Session is not authorized или not authorized after reconnect

Сервер не проводит вход по коду через stdio. Создайте сессию вне сервера командой uv run session_string_generator.py --qr или --phone и пропишите TELEGRAM_SESSION_STRING в .env.

Telegram отклоняет данные приложения: Invalid API credentials

Сверьте TELEGRAM_API_ID и TELEGRAM_API_HASH на my.telegram.org/apps.

AuthKeyDuplicatedError или Another telegram-mcp process is already connected with this session

Одну сессию пытались подключить два процесса, например клиент перезапустил сервер до выхода старого. Оставьте один экземпляр и повторите; для нескольких клиентов дайте каждому свою сессию через TELEGRAM_SESSION_STRINGS.

Ошибки авторизации после смены пароля Telegram

Сгенерируйте строку сессии заново.

Частые вопросы

Это бот или мой аккаунт?

Ваш аккаунт: сервер работает через Telethon от имени пользователя, вошедшего через строку сессии. Агент видит те же чаты, что и вы.

Как оставить агенту только чтение?

Добавьте в env TELEGRAM_EXPOSED_TOOLS=read-only. Чтобы разрешить пару пишущих инструментов поверх чтения, укажите read-only+send_message,reply_to_message.

Можно подключить несколько аккаунтов?

Да, через переменные с суффиксом: TELEGRAM_SESSION_STRING_WORK, TELEGRAM_SESSION_STRING_PERSONAL и так далее. Инструменты принимают метку аккаунта.

Как поставить в Claude Desktop без правки JSON?

Соберите расширение командой npx @anthropic-ai/mcpb pack . telegram-mcp.mcpb в папке репозитория и откройте файл в Claude Desktop. Он сам поставит Python и зависимости и спросит API ID, API hash и строку сессии.

Агент не выполнит команду из чужого сообщения?

Сервер считает сообщения, имена и названия чатов недоверенным содержимым: чистит управляющие символы, отдаёт их структурированным JSON и помечает как пользовательские.

Работает ли сервер из России?

Сервер ходит в Telegram напрямую с вашего компьютера; при необходимости трафик направляется через прокси socks5, socks4, http или MTProxy переменными TELEGRAM_PROXY_*.