Telegram Notification MCP Server

MCP-сервер (Model Context Protocol), который отправляет уведомления в Telegram, когда Claude Code завершает задачи. Создан на TypeScript с использованием Cloudflare Agents SDK и разворачивается на Cloudflare Workers.

📢 Предпочитаете Discord? Ознакомьтесь с Discord Notification MCP для уведомлений в Discord.

Возможности

• 🤖 MCP-инструмент: Предоставляет инструмент send_telegram_message для отправки уведомлений

• 🚀 Cloudflare Workers: Работает в бессерверном режиме с глобальным распределением

• 🔐 Аутентификация: Требуется bearer-токен, хранящийся как секрет Cloudflare

• 🌐 Streamable HTTP: Использует современный stateless MCP-транспорт

• 💬 Форматирование сообщений: Поддерживает форматирование Markdown и HTML

• 📝 Форматирование: Поддерживает форматирование сообщений в Markdown и HTML

Related MCP server: mcp-telegram-claudecode

Архитектура

Этот сервер реализует спецификацию MCP с помощью Cloudflare Agents SDK:

• POST /mcp: Stateless Streamable HTTP endpoint для MCP-взаимодействия

• GET /sse: Возвращает 410 Gone; устаревшие SSE-клиенты должны перейти на /mcp

• Создан на TypeScript, MCP SDK и Cloudflare Agents SDK

• Корректная обработка ошибок JSON-RPC 2.0

• Включён режим совместимости с Node.js

Настройка

Предварительные требования

1. Telegram-бот: Создайте бота через @BotFather и получите токен бота

2. Chat ID: Получите свой chat ID, отправив сообщение вашему боту и посетив:

   https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates

3. Аккаунт Cloudflare: Зарегистрируйтесь на cloudflare.com

Установка

1. Клонируйте этот репозиторий

2. Установите зависимости:

   pnpm install

Конфигурация

1. Создайте файл .dev.vars из примера:

   cp .dev.vars.example .dev.vars

   Затем отредактируйте .dev.vars, указав токен вашего бота и chat ID. Этот файл используется как для локальной разработки, так и для развёртывания.

2. Для продакшн-развёртывания сгенерируйте MCP bearer-токен и настройте секреты Cloudflare:

   openssl rand -hex 32
   pnpm exec wrangler secret put BOT_TOKEN
   pnpm exec wrangler secret put DEFAULT_CHAT_ID  # Optional
   pnpm exec wrangler secret put MCP_AUTH_TOKEN

   Примечание: DEFAULT_CHAT_ID необязателен. Если он не задан, вы должны указать параметр chat_id при вызове инструмента send_telegram_message.

3. При необходимости обновите wrangler.toml, указав имя вашего worker

Развёртывание

Разверните на Cloudflare Workers:

Развёртывание с помощью Wrangler:

# First set secrets
pnpm exec wrangler secret put BOT_TOKEN
pnpm exec wrangler secret put DEFAULT_CHAT_ID  # Optional

# Then deploy
pnpm run deploy

Альтернатива: непрерывное развёртывание

Вы также можете настроить непрерывное развёртывание прямо из панели управления Cloudflare. Подробнее о интеграции git с Cloudflare

Конфигурация Claude Code

Добавьте MCP-сервер в Claude Code, используя Streamable HTTP и тот же bearer-токен:

# For production deployment
claude mcp add --scope user --transport http \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  telegram-notify https://your-worker-name.workers.dev/mcp

# For local development
claude mcp add --transport http \
  --header "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  telegram-notify http://localhost:8787/mcp

Токен — это клиентский доступ к MCP endpoint, а не токен Telegram-бота. Никогда не помещайте токен бота в MCP-конфигурацию Claude.

Вы можете проверить конфигурацию с помощью:

claude mcp list

Использование

После настройки Claude Code сможет отправлять уведомления в ваш Telegram, когда это необходимо.

Доступный инструмент

send_telegram_message: Отправка уведомления в Telegram

• text (обязательный): Текст отправляемого сообщения

• chat_id (необязательный): Chat ID в Telegram (используется DEFAULT_CHAT_ID, если не указан)

• parse_mode (необязательный): "Markdown" или "HTML" для форматирования сообщения

• disable_notification (необязательный): Отправка сообщения без звука

Пример использования:

// Uses DEFAULT_CHAT_ID from environment
await send_telegram_message({ text: "Task completed!" })

// Send to specific chat (overrides DEFAULT_CHAT_ID)
await send_telegram_message({ text: "Hello!", chat_id: "123456789" })

// Send with Markdown formatting
await send_telegram_message({ 
  text: "*Bold* and _italic_ text", 
  parse_mode: "Markdown" 
})

Когда вы будете получать уведомления

Claude Code отправляет уведомления, когда:

• Вы явно просите: «уведоми меня, когда закончишь» или «сообщи мне в Telegram»

• Во время выполнения возникают ошибки

• Достигнуты важные этапы

• Требуется ввод данных или вмешательство пользователя

Примеры сценариев

# You say: "Deploy to production and notify me when done"
# Result: 🤖 Claude Code Notification
#         Deployment completed successfully! The app is now live.

# You say: "Run all tests and let me know the results"
# Result: 🤖 Claude Code Notification
#         All tests passed! 52/52 tests successful.

# You say: "Process this data and notify me if there are any errors"
# Result: 🤖 Claude Code Notification
#         Error: Failed to process row 451 - invalid date format

Примеры уведомлений

Примеры для CLAUDE.md

Чтобы побудить Claude Code эффективно использовать уведомления Telegram, добавьте это в ваш CLAUDE.md:

# Telegram Notifications

Use the mcp__telegram-notify__send_telegram_message tool to send notifications to Telegram.

- Always send a Telegram notification when:
  - A task is fully complete
  - You need user input to continue
  - An error occurs that requires user attention
  - The user explicitly asks for a notification (e.g., "notify me", "send me a message", "let me know")

- Include relevant details in notifications:
  - For builds/tests: success/failure status and counts
  - For errors: the specific error message and file location

- Use concise, informative messages like:
  - "✅ Build completed successfully (2m 34s)"
  - "❌ Tests failed: 3/52 failing in auth.test.ts"
  - "⚠️ Need permission to modify /etc/hosts"

Разработка

Локальный запуск:

# Start local development server
pnpm dev

Для локальной разработки Wrangler автоматически загрузит переменные окружения из вашего файла .dev.vars.

Запустите все проверки перед развёртыванием:

pnpm build

Эта команда выполняет:

1. pnpm format — форматирование кода с помощью Biome

2. pnpm lint:fix — исправление проблем линтинга

3. pnpm cf-typegen — генерация типов Cloudflare

4. pnpm type-check — проверка типов TypeScript

Тестирование сервера:

# An unauthenticated request must return HTTP 401
curl -i http://localhost:8787/mcp

# Claude Code performs the authenticated MCP handshake and health check
claude mcp list

Отладка

Проверка аутентификации

Вы можете убедиться, что endpoint отклоняет запросы без bearer-токена:

curl -i http://localhost:8787/mcp

Это должно вернуть 401 Unauthorized. Затем используйте claude mcp list, чтобы проверить аутентифицированное клиентское подключение.

Частые проблемы

1. 401 Unauthorized: Убедитесь, что заголовок Authorization: Bearer ... клиента совпадает с секретом Cloudflare MCP_AUTH_TOKEN.

2. MCP переподключается или истекает по таймауту: Убедитесь, что клиент использует HTTP-транспорт и endpoint /mcp, а не устаревший /sse.

3. Уведомления Telegram не отправляются: Проверьте, что BOT_TOKEN и DEFAULT_CHAT_ID корректно заданы в окружении Worker.

Технические детали

• Язык: TypeScript (целевая версия ES2021)

• Среда выполнения: Cloudflare Workers с совместимостью с Node.js

• Протокол: MCP (Model Context Protocol)

• Транспорт: Stateless Streamable HTTP

• Наблюдаемость: Включена для мониторинга

Ссылки

Этот проект создан на основе следующих руководств:

• Build a Remote MCP server - Cloudflare Agents

• Model Context Protocol (MCP) - Cloudflare Agents

• MCP Transport Methods - Cloudflare Agents

• Cloudflare MCP Template (remote-mcp-authless)

Лицензия

MIT