DEV Community

Manuel Bruña
Manuel Bruña

Posted on

MCP Telegram Agent: Letting AI Agents Notify You and Wait for Control Replies

#mcp #ai #automation #tutorial

MCP Telegram Agent: Letting AI Agents Notify You and Wait for Control Replies

I built MCP Telegram Agent because agents need a simple way to reach humans outside the editor.

Repository:

https://github.com/tecnomanu/mcp-telegram-agent

The basic feature is easy to explain: an MCP-compatible agent can send a Telegram message with one tool call.

The more interesting part is the workflow around it:

  • guided onboarding
  • config verification
  • npx execution
  • notification delivery
  • update inspection
  • reply-based checkpoints
  • control replies for longer agent runs

This is not meant to be a big chat platform. It is a small MCP server over stdio that gives agents one practical communication channel.

Why agents need notifications

Many agent tasks do not need constant human attention.

Examples:

  • run a long test suite
  • generate videos
  • publish posts
  • inspect a website
  • wait for a deployment
  • process a batch of files
  • ask for approval before a risky step

Keeping the whole interaction trapped inside an IDE tab is not always ergonomic. Sometimes the useful behavior is:

  1. start the task
  2. let the agent work
  3. get a Telegram message when something needs attention
  4. reply from the phone
  5. let the agent continue or stop

That is the gap MCP Telegram Agent tries to cover.

Installation

Recommended MCP config uses npx:

{
  "mcpServers": {
    "telegram-agent": {
      "command": "npx",
      "args": ["-y", "mcp-telegram-agent"],
      "env": {
        "BOT_TELEGRAM_TOKEN": "123456789:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
        "BOT_TELEGRAM_CHAT_ID": "123456789"
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

Local development is also possible:

npm install
npm run check
npm run build
npm run dev
Enter fullscreen mode Exit fullscreen mode

The package exposes:

{
  "name": "mcp-telegram-agent",
  "version": "0.1.0",
  "bin": {
    "mcp-telegram-agent": "dist/index.js"
  }
}
Enter fullscreen mode Exit fullscreen mode

Environment variables

Recommended:

BOT_TELEGRAM_TOKEN=123456789:AAxxxxxxxxxxxxxxxxxxxxxxxxxxxx
BOT_TELEGRAM_CHAT_ID=123456789
Enter fullscreen mode Exit fullscreen mode

Compatibility aliases:

BOT_TELEGRAM_ID
BOT_TELEGRAM_URL
Enter fullscreen mode Exit fullscreen mode

Optional:

BOT_TELEGRAM_TIMEOUT_MS=10000
BOT_TELEGRAM_THREAD_ID=123
BOT_TELEGRAM_API_BASE_URL=https://api.telegram.org
Enter fullscreen mode Exit fullscreen mode

Security rule: prefer BOT_TELEGRAM_TOKEN over a full legacy URL. A token is easier to manage and mask.

The simple tool call

Once configured, an agent can call:

{
  "message": "Build finished. 42 tests passed. Ready for review.",
  "parseMode": "Markdown",
  "disableNotification": false
}
Enter fullscreen mode Exit fullscreen mode

The MCP tool returns something like:

Notification sent to Telegram (status 200, message_id=207).
Enter fullscreen mode Exit fullscreen mode

That alone is useful. But setup is usually where tools fail, so the repo includes onboarding helpers.

Guided onboarding

The setup command flow is designed for agents:

/setup-mcp-telegram-agent
Enter fullscreen mode Exit fullscreen mode

Expected flow:

  1. Add a minimal MCP config using npx -y mcp-telegram-agent.
  2. Ask the user for a Telegram bot token.
  3. Call telegram_onboarding_prepare.
  4. Ask the user to send the setup code to the bot.
  5. Call telegram_onboarding_verify in confirmation mode.
  6. Ask the user to confirm the exact chat_id.
  7. Verify again with expectedChatId.
  8. Apply the generated MCP config.
  9. Send a test notification.

The important detail: the agent should not silently pick a chat_id.

Telegram updates can include multiple chats, old messages, or group contexts. The setup flow supports cautious mode with explicit confirmation, because sending automation messages to the wrong chat is a bad failure mode.

BotFather setup

The manual Telegram side is standard:

  1. Open @BotFather.
  2. Send /newbot.
  3. Choose display name.
  4. Choose username ending in bot.
  5. Save the token securely.
  6. Start a chat with the bot.
  7. Send the setup code from the onboarding flow.

If doing it manually, the raw Telegram API check looks like this:

curl "https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates"
Enter fullscreen mode Exit fullscreen mode

Look for:

message.chat.id
message.message_id
Enter fullscreen mode Exit fullscreen mode

A mock agent conversation

Here is the kind of interaction I want from an agent:

Telegram

Agent Project Bot
10:42
FrameVOX render finished.

Project: launch-reel
Output: output/crewdesk-launch.mp4
Checks:
- lint passed
- voice generated
- render completed

Reply:
continue FVX92 to publish
stop FVX92 to hold

You
10:43
continue FVX92

Agent Project Bot
10:43
Acknowledged. Continuing publish step.
Enter fullscreen mode Exit fullscreen mode

That is not a full chat client. It is a control checkpoint.

The agent sends a structured message with enough context. The user replies with a constrained command. The agent polls for replies, validates the control code, acknowledges, and continues.

Control loop tools

The repository includes tools for this pattern:

  • telegram_send_control_checkpoint
  • telegram_poll_control_replies
  • telegram_ack_control_reply

A typical checkpoint:

{
  "title": "Production deploy checkpoint",
  "summary": "Tests passed and image built. Reply continue DEP91 to deploy, or stop DEP91 to hold.",
  "instanceId": "codex-local-2026-06-09",
  "controlCode": "DEP91"
}
Enter fullscreen mode Exit fullscreen mode

Then the agent polls:

{
  "replyToMessageId": 207,
  "instanceId": "codex-local-2026-06-09",
  "controlCode": "DEP91",
  "actionFilter": "continue",
  "waitSeconds": 30
}
Enter fullscreen mode Exit fullscreen mode

After a valid reply:

{
  "chatId": "123456789",
  "replyToMessageId": 208,
  "status": "accepted",
  "summary": "Continuing deployment."
}
Enter fullscreen mode Exit fullscreen mode

The design is intentionally boring:

  • stable instance ID for multi-IDE isolation
  • control code to avoid accidental replies
  • reply target to bind the action to a specific checkpoint
  • acknowledgement so the user knows the agent heard it

How an agent should use it

For normal notifications:

Use send_telegram_notification when the user should know something happened, but no decision is needed.
Enter fullscreen mode Exit fullscreen mode

For risky or long-running workflows:

Use a checkpoint when the next step needs explicit human control.
Enter fullscreen mode Exit fullscreen mode

For setup:

Use onboarding tools. Do not tell the user to manually inspect getUpdates unless automation fails.
Enter fullscreen mode Exit fullscreen mode

For security:

Never print full bot tokens. Mask them. Confirm chat_id before final config.
Enter fullscreen mode Exit fullscreen mode

Example: agent publishing workflow

Imagine an agent that writes and publishes articles.

The workflow can be:

  1. Generate draft.
  2. Run validation.
  3. Publish as draft or live article.
  4. Send Telegram notification with title and URL.
  5. If manual review is required, send a checkpoint before publishing live.

Example final notification:

{
  "message": "*DEV post published*\n\nTitle: FrameVOX: A Video Production CLI for Agent-Made Social Videos\nURL: https://dev.to/tecnomanu/example",
  "parseMode": "Markdown"
}
Enter fullscreen mode Exit fullscreen mode

That is a small thing, but it changes the feel of long agent work. The user no longer has to keep checking the terminal or editor.

What this is not

MCP Telegram Agent is not trying to be:

  • a replacement for Slack
  • a task database
  • a memory system
  • a general agent runtime
  • a remote code execution layer

It is one communication tool. That narrow scope is a feature.

Agents become easier to trust when each tool has a clear boundary.

Repository

https://github.com/tecnomanu/mcp-telegram-agent

If you build agents that run longer than a few seconds, give them a way to report back. Telegram is not the only possible channel, but it is fast, familiar, and good enough for many personal and small-team workflows.

Top comments (0)