Skip to main content
Glama
telegram-mcp-server

telegram-mcp-server

by a-shipilo

telegram-mcp-server

CI License: MIT

MCP-сервер, через который Claude пишет вам в Telegram от имени вашего бота. Он нужен прежде всего для уведомлений: итог рутины, конец долгой задачи, найденная проблема. Сервер запускается через uvx прямо из GitHub, устанавливать ничего не нужно.

English: a minimal open-source MCP server that lets Claude send you Telegram messages through your own bot: notifications from routines, scheduled and long-running tasks. Messages always go to the single chat configured on the server. Run it with uvx --from git+https://github.com/a-shipilo/telegram-mcp-server telegram-mcp-server.

Возможности

Инструмент

Что делает

send_message

отправляет сообщение в чат из TELEGRAM_CHAT_ID

Параметры send_message:

Параметр

По умолчанию

Описание

text

—

текст сообщения, обязательно

format

html

html — разметка тегами Telegram; text — текст как есть

silent

false

доставить без звука

link_preview

false

показывать превью первой ссылки

  • Текст длиннее 4096 символов отправляется несколькими сообщениями. Разбивка идёт по абзацам, строкам или словам, а звук уведомления будет только у первой части.

  • Если Telegram не разберёт HTML (например, Claude использовал неподдерживаемый тег), сообщение всё равно отправится обычным текстом, без тегов. Claude узнает об этом из ответа инструмента.

  • Бот пишет только в чат из настроек: выбрать другой чат Claude не может.

Related MCP server: mcp-telegram-claudecode

Установка

Нужен установленный uv (brew install uv на macOS).

1. Создайте бота

  1. Откройте @BotFather, отправьте /newbot и задайте имя бота.

  2. Скопируйте токен вида 123456789:AAE....

  3. Откройте своего бота по ссылке от BotFather и нажмите «Запустить». Пока вы этого не сделали, бот не может написать вам первым.

WARNING

Токен — это пароль: с ним любой может писать от имени бота и читать то, что пишут боту. Не публикуйте его и не коммитьте в репозитории. Если токен утёк, выпустите новый:/revoke в @BotFather.

2. Узнайте ID чата

TELEGRAM_BOT_TOKEN=123456789:AAE... uvx --from git+https://github.com/a-shipilo/telegram-mcp-server telegram-mcp-server chat-id

Команда покажет чаты, из которых боту писали за последние 24 часа:

Бот: @my_notify_bot
Чаты, из которых боту писали за последние 24 часа:
  123456789       private     Иван (@ivan)
  -1001234567890  supergroup  Мониторинг
Укажите нужный ID в TELEGRAM_CHAT_ID.

Для личных уведомлений нужен ваш личный чат (private). Чтобы бот писал в группу, добавьте его туда и отправьте в группе /start. Чтобы бот писал в канал, сделайте его администратором канала.

3. Проверьте отправку

TELEGRAM_BOT_TOKEN=123456789:AAE... TELEGRAM_CHAT_ID=123456789 uvx --from git+https://github.com/a-shipilo/telegram-mcp-server telegram-mcp-server test

4. Подключите сервер

Claude Code

Сервер добавляется на уровне пользователя (-s user), чтобы он был доступен во всех проектах и в задачах по расписанию:

claude mcp add telegram -s user -e TELEGRAM_BOT_TOKEN=123456789:AAE... -e TELEGRAM_CHAT_ID=123456789 -- uvx --from git+https://github.com/a-shipilo/telegram-mcp-server@v0.1.0 telegram-mcp-server

Claude Desktop

  1. Откройте Settings → Developer → Edit Config. Откроется файл claude_desktop_config.json.

  2. Добавьте сервер в mcpServers:

{
  "mcpServers": {
    "telegram": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/a-shipilo/telegram-mcp-server@v0.1.0",
        "telegram-mcp-server"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456789:AAE...",
        "TELEGRAM_CHAT_ID": "123456789"
      }
    }
  }
}
  1. Полностью перезапустите Claude Desktop. Сервер telegram появится в Settings → Developer со статусом running.

@v0.1.0 фиксирует версию. Чтобы всегда брать последнюю версию из main, уберите @v0.1.0. Для обновления добавьте в args перед --from флаг --refresh.

Если в логах spawn uvx ENOENT, укажите полный путь к uvx (узнать его: which uvx), например "command": "/opt/homebrew/bin/uvx".

Уведомления из рутин

Достаточно попросить об уведомлении в тексте задачи:

…Когда закончишь, отправь мне в Telegram короткий итог: что сделано и что требует моего внимания. Если всё в порядке и делать ничего не нужно, отправь сообщение без звука.

Задачи по расписанию на вашем компьютере (Claude Desktop, Claude Code) используют ваши локальные MCP-серверы. Достаточно подключить сервер, как описано выше: в Claude Code — с -s user.

Облачные рутины (claude.ai/code) выполняются в облачном окружении, поэтому локальные настройки туда не попадают:

  1. Добавьте в репозиторий, с которым работает рутина, файл .mcp.json. Токен в него не пишите: Claude Code подставит его из переменных окружения.

    {
      "mcpServers": {
        "telegram": {
          "command": "uvx",
          "args": ["--from", "git+https://github.com/a-shipilo/telegram-mcp-server@v0.1.0", "telegram-mcp-server"],
          "env": {
            "TELEGRAM_BOT_TOKEN": "${TELEGRAM_BOT_TOKEN}",
            "TELEGRAM_CHAT_ID": "${TELEGRAM_CHAT_ID}"
          }
        }
      }
    }
  2. В настройках облачного окружения задайте переменные TELEGRAM_BOT_TOKEN и TELEGRAM_CHAT_ID.

  3. Там же разрешите доступ к api.telegram.org: по умолчанию облачное окружение пускает только к пакетным репозиториям и распространённым API. Выберите доступ Custom и добавьте этот домен. Если в окружении нет uv, установите его в setup-скрипте: pip install uv.

Настройки

Переменная

По умолчанию

Описание

TELEGRAM_BOT_TOKEN

—

токен бота от @BotFather, обязательно

TELEGRAM_CHAT_ID

—

ID чата, куда писать: число (123456789, -1001234567890) или @канал, обязательно

TELEGRAM_API_URL

https://api.telegram.org

адрес Bot API, если у вас свой сервер Bot API или обратный прокси

Если Telegram доступен только через прокси, задайте HTTPS_PROXY, например HTTPS_PROXY=http://127.0.0.1:8080. Для SOCKS-прокси запускайте сервер с uvx --with socksio.

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

Команды

Команда

Что делает

telegram-mcp-server

запускает MCP-сервер (stdio)

telegram-mcp-server chat-id

показывает ID чатов, из которых недавно писали боту

telegram-mcp-server test ["текст"]

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

telegram-mcp-server --version

версия

chat-id читает последние сообщения через getUpdates, но не помечает их прочитанными. Для уведомлений лучше завести отдельного бота: если бот уже где-то работает, chat-id может помешать его опросу, а при настроенном webhook список чатов недоступен. В этом случае учтите, что ID личного чата совпадает с вашим ID в Telegram, его можно узнать, например, у @userinfobot.

Разработка

git clone https://github.com/a-shipilo/telegram-mcp-server.git
cd telegram-mcp-server
uv sync
uv run pytest
uv run ruff check . && uv run ruff format --check .

Локальная отладка в MCP Inspector:

npx @modelcontextprotocol/inspector -e TELEGRAM_BOT_TOKEN=... -e TELEGRAM_CHAT_ID=... uv run telegram-mcp-server

Лицензия

MIT

Available Tools

1 tool
send_messageA

Отправить пользователю сообщение в Telegram от имени его бота.

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

Inputs: text (required), format, silent, link_preview. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 1 tool

    Disambiguation5/5

    Only one tool exists, so there is no possibility of confusion or misselection. The tool has a clear single purpose.

    Naming Consistency5/5

    The single tool name 'send_message' follows a clear verb_noun pattern, consistent with common MCP naming conventions. No inconsistencies are possible with only one tool.

    Tool Count2/5

    A single tool is very thin for a server named 'telegram-mcp-server', which implies broader Telegram capabilities. Even if intended solely for notifications, the scope is extremely narrow.

    Completeness2/5

    The server only supports sending messages, with no ability to receive, edit, or manage chats. It is severely limited compared to the expected functionality of a Telegram MCP server, though it may satisfy a basic notification use case.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude Code to send Telegram notifications when tasks complete, errors occur, or user intervention is needed. Runs serverless on Cloudflare Workers with support for formatted messages and flexible chat targeting.
      266 npm
      22
      MIT
    • F
      license
      Not graded
      quality
      F
      maintenance
      Enables Claude to interact with your Telegram account, including reading messages, searching conversations, and sending messages.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to send messages, media, and manage Telegram chat messages through a Telegram bot, including sending photos, documents, and editing or deleting messages.
      MIT