Skip to main content
Glama
Sign In
telegram-mcp-notify

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Telegram Notification MCP

      kstonekuan
      A
      license
      Not graded
      quality
      D
      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.
      168 npm
      22
      MIT