MCP Telegram Bot Server

MCP (Model Context Protocol) сервер для работы с Telegram Bot API. Предоставляет инструменты для публикации контента, создания опросов, отправки реакций и управления каналом Telegram.

Возможности

• 📝 Отправка текстовых сообщений с поддержкой HTML, Markdown и MarkdownV2
• 📸 Публикация фотографий с подписями
• 📄 Отправка документов (файлы, PDF, и т.д.)
• 🗳️ Создание опросов (обычные и викторины)
• 👍 Отправка реакций (эмодзи) к сообщениям
• 📌 Закрепление и открепление сообщений
• 📊 Получение информации о канале и количестве участников

Установка

Глобальная установка из npm

npm install -g mcp-telegram-bot

Локальная установка

npm install mcp-telegram-bot

Настройка

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

   • Отправьте /newbot боту @BotFather
   • Получите токен бота
   • Добавьте бота в ваш канал как администратора

2. Настройте переменные окружения:

   Создайте файл .env в корне проекта:

   TELEGRAM_BOT_TOKEN=your_bot_token_here
   TELEGRAM_CHANNEL_ID=@your_channel_username

   Или используйте готовый пример:

   cp env.example .env

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

Запуск с помощью npx (рекомендуется)

npx mcp-telegram-bot

Локальное тестирование без компиляции

# Установите зависимости
npm install

# Запустите в режиме разработки
npx tsx src/index.ts

Сборка и запуск

# Сборка проекта
npm run build

# Запуск собранной версии
npm start

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

send_message

Отправляет текстовое сообщение в канал.

Параметры:

• text (обязательный) - текст сообщения
• parse_mode (опциональный) - режим парсинга: HTML, Markdown, MarkdownV2

Пример:

{
  "name": "send_message",
  "arguments": {
    "text": "Привет! Это тестовое сообщение",
    "parse_mode": "HTML"
  }
}

send_photo

Отправляет фотографию в канал.

Параметры:

• photo_url (обязательный) - URL фотографии
• caption (опциональный) - подпись к фотографии
• parse_mode (опциональный) - режим парсинга подписи

Пример:

{
  "name": "send_photo",
  "arguments": {
    "photo_url": "https://example.com/image.jpg",
    "caption": "Красивая фотография!",
    "parse_mode": "HTML"
  }
}

send_document

Отправляет документ в канал.

Параметры:

• document_url (обязательный) - URL документа
• caption (опциональный) - подпись к документу
• parse_mode (опциональный) - режим парсинга подписи

send_poll

Создает опрос в канале.

Параметры:

• question (обязательный) - вопрос опроса
• options (обязательный) - массив вариантов ответов (2-10)
• is_anonymous (опциональный) - анонимный опрос (по умолчанию true)
• type (опциональный) - тип опроса: regular или quiz
• correct_option_id (опциональный) - ID правильного ответа для викторины
• explanation (опциональный) - объяснение для викторины

Пример:

{
  "name": "send_poll",
  "arguments": {
    "question": "Какой ваш любимый язык программирования?",
    "options": ["JavaScript", "Python", "TypeScript", "Go"],
    "is_anonymous": true,
    "type": "regular"
  }
}

send_reaction

Отправляет реакцию (эмодзи) к сообщению.

Параметры:

• message_id (обязательный) - ID сообщения
• emoji (опциональный) - эмодзи для реакции (по умолчанию 👍)

pin_message

Закрепляет сообщение в канале.

Параметры:

• message_id (обязательный) - ID сообщения
• disable_notification (опциональный) - отключить уведомления

unpin_message

Открепляет сообщение в канале.

Параметры:

• message_id (обязательный) - ID сообщения

get_channel_info

Получает информацию о канале.

get_chat_member_count

Получает количество участников канала.

Интеграция с MCP клиентами

Claude Desktop

Добавьте в конфигурацию Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "telegram-bot": {
      "command": "npx",
      "args": ["mcp-telegram-bot"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your_bot_token",
        "TELEGRAM_CHANNEL_ID": "@your_channel"
      }
    }
  }
}

Другие MCP клиенты

Сервер совместим с любыми MCP клиентами, поддерживающими stdio транспорт.

Разработка

Структура проекта

├── src/
│   └── index.ts          # Основной файл сервера
├── dist/                 # Скомпилированные файлы
├── package.json          # Конфигурация npm
├── tsconfig.json         # Конфигурация TypeScript
├── env.example           # Пример переменных окружения
└── README.md            # Документация

Скрипты

• npm run build - сборка проекта
• npm run start - запуск собранной версии
• npm run dev - запуск в режиме разработки
• npm run prepublishOnly - подготовка к публикации

Требования

• Node.js >= 18.0.0
• Telegram Bot Token
• Права администратора бота в канале

Лицензия

MIT License

Поддержка

Если у вас возникли вопросы или проблемы:

1. Проверьте, что бот добавлен в канал как администратор
2. Убедитесь, что токен бота корректный
3. Проверьте формат ID канала (должен начинаться с @ или быть числовым ID)

Changelog

v1.0.0

• Первоначальный релиз
• Поддержка основных функций Telegram Bot API
• Интеграция с MCP протоколом