telegram-mcp-server
Allows sending Telegram messages to a configured chat via a bot, with support for HTML formatting, silent delivery, link previews, and splitting long messages into multiple parts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@telegram-mcp-server Send me a Telegram message when the build finishes with a summary of results."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: mcp-telegram-claudecode
Установка
Нужен установленный uv
(brew install uv на macOS).
1. Создайте бота
Откройте @BotFather, отправьте
/newbotи задайте имя бота.Скопируйте токен вида
123456789:AAE....Откройте своего бота по ссылке от BotFather и нажмите «Запустить». Пока вы этого не сделали, бот не может написать вам первым.
Токен — это пароль: с ним любой может писать от имени бота и читать то, что пишут боту.
Не публикуйте его и не коммитьте в репозитории. Если токен утёк, выпустите новый:/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 test4. Подключите сервер
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-serverClaude Desktop
Откройте Settings → Developer → Edit Config. Откроется файл
claude_desktop_config.json.Добавьте сервер в
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"
}
}
}
}Полностью перезапустите 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) выполняются в облачном окружении, поэтому локальные настройки туда не попадают:
Добавьте в репозиторий, с которым работает рутина, файл
.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}" } } } }В настройках облачного окружения задайте переменные
TELEGRAM_BOT_TOKENиTELEGRAM_CHAT_ID.Там же разрешите доступ к
api.telegram.org: по умолчанию облачное окружение пускает только к пакетным репозиториям и распространённым API. Выберите доступ Custom и добавьте этот домен. Если в окружении нетuv, установите его в setup-скрипте:pip install uv.
Настройки
Переменная | По умолчанию | Описание |
| — | токен бота от @BotFather, обязательно |
| — | ID чата, куда писать: число ( |
|
| адрес Bot API, если у вас свой сервер Bot API или обратный прокси |
Если Telegram доступен только через прокси, задайте HTTPS_PROXY, например HTTPS_PROXY=http://127.0.0.1:8080.
Для SOCKS-прокси запускайте сервер с uvx --with socksio.
Если сервер запущен без нужных переменных, он всё равно стартует, а send_message вернёт
понятную ошибку: так Claude сможет сказать, что именно не настроено.
Команды
Команда | Что делает |
| запускает MCP-сервер (stdio) |
| показывает ID чатов, из которых недавно писали боту |
| отправляет проверочное сообщение в |
| версия |
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Лицензия
Available Tools
1 toolsend_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
Scored across 1 tool
Only one tool exists, so there is no possibility of confusion or misselection. The tool has a clear single purpose.
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.
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.
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
Related MCP Connectors
Let AI assistants post to your Telegram chats, groups and channels. Not affiliated with Telegram.
Run a Telegram channel from your AI agent. Posts go out through your own bot, not your account.
Your Telegram, WhatsApp, Instagram, mail and calendar in Claude or ChatGPT. Never sends messages.
Telegram bridge for your MCP-compatible agent. Bidirectional, no LLM in our stack.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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 npm22MIT
- AlicenseAqualityDmaintenanceEnables Claude Code to send and receive messages via Telegram for remote interaction and approval of sensitive operations.8575 npm7MIT
- FlicenseNot gradedqualityFmaintenanceEnables Claude to interact with your Telegram account, including reading messages, searching conversations, and sending messages.-
- AlicenseNot gradedqualityDmaintenanceEnables Claude to send messages, media, and manage Telegram chat messages through a Telegram bot, including sending photos, documents, and editing or deleting messages.MIT