Skip to main content
Glama
hsynj

Claude Code Telegram Notifier MCP Server

by hsynj
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Claude Code Telegram Notifier MCP Server šŸ¤–šŸ“²

License: MIT TypeScript Model Context Protocol

A Model Context Protocol (MCP) server that connects Claude Code and Claude Desktop to Telegram. Receive real-time push notifications on your phone or desktop whenever Claude starts long tasks, hits key milestones, encounters blockers, or finishes work ā€” perfect for when you are away from your keyboard (AFK).

āœØ Features

  • šŸ”” Proactive Notifications: Claude notifies you automatically about task status without manual intervention.

  • šŸš¦ Status Types:

    • info ā„¹ļø: Task started, background work initiated.

    • success āœ…: Milestone reached, task completed.

    • warning āš ļø: Non-critical issue, retry, or blocker.

    • action_required šŸšØ: Human intervention needed (approval, missing API key, confirmation).

  • šŸ›”ļø Resilient Delivery: Automatic fallback to plain text if Markdown entity parsing fails due to unescaped code or paths.

  • āš™ļø Dual Configuration: Supports both .env file and MCP configuration env block.

  • šŸ”Œ Universal Compatibility: Works with Claude Code CLI and Claude Desktop app.

Related MCP server: telegram-mcp-notify

šŸ“‹ Prerequisites

  1. Node.js (v18 or higher) & npm

  2. Telegram Bot Token:

    • Open Telegram and message @BotFather.

    • Send /newbot and follow the instructions to create your bot.

    • Copy the API token provided.

  3. Telegram User ID:

šŸš€ Installation & Setup

1. Clone & Build

git clone git@github.com:hsynj/ClaudeCode-Telegram-MCPTool.git
cd ClaudeCode-Telegram-MCPTool
npm install
npm run build

2. Configure Environment

Copy the example environment file and fill in your credentials:

cp .env.example .env

Edit .env:

BOT_TOKEN=123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ
ADMIN_ID=987654321

Note: You can also specify these variables directly in your Claude configuration files.

šŸ› ļø Configuration with Claude

Option A: Claude Code CLI

Add the server to Claude Code using claude mcp add:

claude mcp add telegram-notifier node /ABSOLUTE_PATH_TO/ClaudeCode-Telegram-MCPTool/dist/index.js -e BOT_TOKEN=YOUR_BOT_TOKEN -e ADMIN_ID=YOUR_ADMIN_ID

Or manually configure your MCP settings file (e.g. ~/.claude/mcp.json or project-level .claude/settings.json):

{
  "mcpServers": {
    "telegram-notifier": {
      "command": "node",
      "args": [
        "/ABSOLUTE_PATH_TO/ClaudeCode-Telegram-MCPTool/dist/index.js"
      ],
      "env": {
        "BOT_TOKEN": "YOUR_BOT_TOKEN",
        "ADMIN_ID": "YOUR_ADMIN_ID"
      }
    }
  }
}

Option B: Claude Desktop App

Edit claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "telegram-notifier": {
      "command": "node",
      "args": [
        "/ABSOLUTE_PATH_TO/ClaudeCode-Telegram-MCPTool/dist/index.js"
      ],
      "env": {
        "BOT_TOKEN": "YOUR_BOT_TOKEN",
        "ADMIN_ID": "YOUR_ADMIN_ID"
      }
    }
  }
}

šŸ§  Automating Proactive Notifications in Claude Code

To make Claude proactively notify you while working, add a rule to ~/.claude/rules/telegram-notifier.md:

# Telegram Notifier Rule

You MUST proactively use the `send_telegram_update` MCP tool to notify the user in the following situations, without the user explicitly asking:

1. **When starting a multi-step or long-running task:** Let the user know you have started working. Use `status: "info"`.
2. **When reaching significant milestones:** If you've completed a major part of a larger task (e.g. "Finished setting up the database, now moving to API routes"). Use `status: "success"`.
3. **When you encounter a blocker or need human intervention:** If a test fails repeatedly, an API key is missing, or you are stuck and need advice. Use `status: "warning"` or `action_required`.
4. **When you need approval:** If you are about to run a destructive command, modify a critical file, or do something that requires explicit permission. Use `status: "action_required"`.
5. **When the task is completely finished:** Let the user know the work is done and they can review it. Use `status: "success"`.

Assume the user is AFK and relies on Telegram notifications to track progress.

šŸ”§ MCP Tool Specification

send_telegram_update

Sends a formatted notification to your Telegram chat.

Parameter

Type

Required

Description

project

string

Yes

Name of the project or repository being worked on.

message

string

Yes

Detailed status log, explanation, or required action.

status

string

Yes

One of info, success, warning, action_required.

title

string

No

Short headline (defaults to "Update").

Message Format Example:

āœ… Milestone Completed
šŸ“‚ Project: my-web-app

Database migrations applied and all 24 unit tests passed.

Status: success

šŸ‘Øā€šŸ’» Development

# Run in development mode with ts-node
npm run dev

# Compile TypeScript
npm run build

# Start compiled server
npm start

šŸ“„ License

This project is licensed under the MIT License.

Available Tools

1 tool
send_telegram_updateA

Send a vital update, progress log, or status notification to the user's Telegram. Use this when starting a long task, when reaching significant milestones, or when you encounter a blocker/need the user to return to the computer to approve an action.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleNoA short title for the update (e.g. 'Task Started', 'Milestone Reached', 'Approval Needed')
statusYesThe type of update
messageYesThe detailed log or message describing current status, what you are doing, or what is needed.
projectYesThe name of the project you are working on

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It does disclose the meaningful side effect ā€” an outbound message delivered to the user's external Telegram ā€” but says nothing about delivery failure, rate limits, whether the call blocks, or what happens if the user is unreachable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, zero waste, with the core action front-loaded and the usage conditions following. Every clause earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a four-parameter notification tool with full schema coverage and no output schema, the description covers purpose and timing adequately. It is slightly short on operational behavior (delivery semantics, failure handling), which is the only meaningful gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (including the status enum) are already documented in the schema. The description lists update categories that loosely correspond to the status values but adds no format, length, or constraint guidance beyond the schema, so the baseline of 3 is correct.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('Send') and resource ('vital update, progress log, or status notification') with the destination ('the user's Telegram'). There are no sibling tools to disambiguate from, and the action is unambiguous to an agent without opening the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly enumerates trigger conditions: starting a long task, reaching significant milestones, encountering a blocker, or needing the user back at the computer to approve an action. This maps directly onto the 'action_required' status and leaves no inference required about when to call it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 1 tool updatev1.0.0
    • First observedsend_telegram_update
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.2/5.0

Scored across 1 tool

Disambiguation5/5

With only a single tool, there is no possibility of confusion or misselection between tools. The tool's purpose is self-evident and unambiguous.

Naming Consistency5/5

The lone name send_telegram_update follows a clear verb_noun snake_case convention. With one tool there is no inconsistency to speak of.

Tool Count3/5

A single tool is borderline thin for a server, though the notifier's scope is narrow. One send operation arguably covers the entire purpose, but it leaves little room for nuance.

Completeness4/5

Sending a notification is the only real operation for a notifier, so the surface covers the domain's core action. Minor gaps exist (e.g. no distinct channels for errors vs. progress), but the stated use cases are handled.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • claude-slack-bridge

    tomeraitz
    A
    license
    Not graded
    quality
    A
    maintenance
    Enables Claude Code to pause and ask questions via Slack, and allows running Claude from Slack with project-aware context, supporting a full-process feature development workflow.
    35
    MIT

  • telegram-mcp-notify

    hyper-tew
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI coding agents to send structured Telegram notifications for events like questions, plan_ready, final, attention_needed, and error.
    MIT

  • rubberduck-mcp

    superiorsd10
    A
    license
    Not graded
    quality
    C
    maintenance
    Enables AI coding assistants to ask for human clarification and share thoughts in real-time, creating natural, engaging coding conversations.
    5 npm
    3
    MIT