Skip to main content
Glama
hyper-tew

telegram-mcp-notify

by hyper-tew
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

telegram-mcp-notify

Notify-only Telegram MCP server for AI coding agents (Cursor, Codex, Claude Code).

IMPORTANT DISCLAIMER (WIP / SELF-USE)

WARNING

This repository is still in active development and currently intended for personal/self use and experimentation. APIs and behavior may change without notice. Use at your own risk.

Related MCP server: Telegram Notifier MCP Server

Breaking Changes in 0.2.0

  • Removed console script: telegram-mcp-listener

  • Removed reply/input internals (inbox, listener lifecycle, pending prompts)

  • Removed singleton lock behavior for server startup

Features

  • Outbound Telegram notifications for:

    • question

    • plan_ready

    • final

    • attention_needed

    • error

  • Notify-only MCP surface:

    • send_telegram_notification

    • telegram_notify_capabilities

  • Cross-platform runtime (Windows and POSIX)

Prerequisites

  • Python 3.11+

  • uv / uvx (recommended) or pip

  • Telegram bot token (from @BotFather)

  • Telegram chat ID

Quick Start: Cursor

Create .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "telegram_notify": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/hyper-tew/telegram-mcp-notify",
        "telegram-mcp-notify"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "123456:ABC-DEF...",
        "TELEGRAM_CHAT_ID": "123456789"
      }
    }
  }
}

Restart Cursor after saving.

Quick Start: Codex

Add to ~/.codex/config.toml:

[mcp_servers.telegram_notify]
command = "uvx"
args = ["--from", "git+https://github.com/hyper-tew/telegram-mcp-notify", "telegram-mcp-notify"]

[mcp_servers.telegram_notify.env]
TELEGRAM_BOT_TOKEN = "123456:ABC-DEF..."
TELEGRAM_CHAT_ID = "123456789"

Or via CLI:

codex mcp add telegram_notify \
  --env TELEGRAM_BOT_TOKEN=123456:ABC-DEF... \
  --env TELEGRAM_CHAT_ID=123456789 \
  -- uvx --from "git+https://github.com/hyper-tew/telegram-mcp-notify" telegram-mcp-notify

Alternative: Pre-install with pip

# From GitHub
pip install git+https://github.com/hyper-tew/telegram-mcp-notify.git

# From local clone
pip install ./telegram-mcp-notify

# Development
pip install -e "./telegram-mcp-notify[dev]"

Then use Python module mode in MCP config:

[mcp_servers.telegram_notify]
command = "python"
args = ["-m", "telegram_mcp_notify.server"]

[mcp_servers.telegram_notify.env]
TELEGRAM_BOT_TOKEN = "123456:ABC-DEF..."
TELEGRAM_CHAT_ID = "123456789"

Environment Variables

Required:

  • TELEGRAM_BOT_TOKEN

  • TELEGRAM_CHAT_ID

Optional:

Variable

Default

Description

TELEGRAM_PARSE_MODE

None

Message parse mode (HTML or Markdown)

TELEGRAM_DISABLE_NOTIFICATION

false

Suppress outbound notifications

TELEGRAM_TIMEOUT_SECONDS

10

HTTP request timeout

Available Tools

Tool

Description

send_telegram_notification

Send a structured Telegram checkpoint notification

telegram_notify_capabilities

Return current server tool/capability surface

Troubleshooting

Symptom

Cause

Fix

No notifications received

Invalid token/chat ID

Verify TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID

Unexpected tools shown

Running old package version

Upgrade/restart MCP runtime

spawn telegram-mcp-notify ENOENT

Executable not on PATH

Use uvx ... telegram-mcp-notify or python -m telegram_mcp_notify.server

spawn uvx ENOENT

uv not installed/on PATH

Install uv and restart the client app

License

MIT

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Telegram Notification MCP

    kstonekuan
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables 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.
    9 npm
    22
    MIT