telegram-mcp-server

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:

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

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

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

Related MCP server: Telegram MCP Server

Установка

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

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

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

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

3. Откройте своего бота по ссылке от 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"
      }
    }
  }
}

3. Полностью перезапустите 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 доступен только через прокси, задайте HTTPS_PROXY, например HTTPS_PROXY=http://127.0.0.1:8080. Для SOCKS-прокси запускайте сервер с uvx --with socksio.

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

Команды

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