Skip to main content
Glama
chilldude

telegram-claude-mcp

by chilldude
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

Telegram MCP Bridge

An MCP server that lets Claude Code send messages and ask questions via Telegram.

When Claude Code needs your input during a coding task, it sends a Telegram message (with optional inline buttons) and waits for your reply.

Claude Code → MCP tool call → this server → Telegram Bot API → your phone
           ← tool result    ← server      ← you tap a button / type a reply

Tools

Tool

Description

ask_user

Send a question with optional buttons, wait for response (10-min timeout)

notify_user

Fire-and-forget notification

Related MCP server: Telegram Notification MCP Server

Setup

1. Create a Telegram Bot

  1. Open Telegram, message @BotFather

  2. Send /newbot, follow prompts — save the bot token

  3. Message your new bot (send anything), then visit:

    https://api.telegram.org/bot<YOUR_TOKEN>/getUpdates

  4. Find your chat ID in the response JSON (result[0].message.chat.id)

2. Clone & Install

git clone https://github.com/yourusername/telegram-claude-mcp.git
cd telegram-claude-mcp
npm install

3. Configure Claude Code

Add to ~/.claude/mcp.json (create the file if it doesn't exist):

{
  "mcpServers": {
    "telegram": {
      "command": "node",
      "args": ["/absolute/path/to/telegram-claude-mcp/telegram-bridge.js"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token",
        "TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

4. Restart Claude Code

The MCP server starts automatically when Claude Code launches. You should see telegram in your MCP server list.

Usage

Claude Code will automatically have access to ask_user and notify_user tools. You can prompt it to use them:

"If you need to ask me something, use the ask_user Telegram tool"

Or Claude may use them when configured in your project's CLAUDE.md.

License

MIT

Available Tools

2 tools
ask_userA

Send a question to the user via Telegram and wait for their response. Optionally include inline buttons for quick replies. Times out after 10 minutes.

ParametersJSON Schema
NameRequiredDescriptionDefault
buttonsNoOptional list of button labels for quick replies (inline keyboard)
messageYesThe question or message to send

TDQS

A4.1/5.0
Behavior4/5

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

With no annotations provided, the description carries the burden and covers key behavior: sends via Telegram, waits for user response, supports optional inline buttons, and adds the explicit 10-minute timeout. It does not state what happens after a timeout, but the core behavior is transparent.

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?

Three tight sentences with no filler; the main verb and behavior are front-loaded, optionality is stated, and the timeout is appended as an important constraint.

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

Completeness3/5

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

For a simple 2-parameter tool, this is mostly complete: it covers message, optional buttons, transport, and timeout. The main missing piece is what happens after timeout or what the returned response looks like, especially since no output schema exists.

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 the baseline is 3. The description adds slight context ('Telegram', 'quick replies') but mostly restates what the schema already says about the message and buttons parameters.

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?

The description names a specific action ('Send a question'), target ('to the user via Telegram'), and key behavior ('wait for their response'). This clearly differentiates it from sibling notify_user, which is for one-way communication.

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

Usage Guidelines4/5

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

The description conveys a clear usage context: use when you need an interactive reply from the user, as opposed to sending a one-way notification. However, it does not explicitly mention notify_user or give when-not-to-use guidance, so it stops short of a 5.

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

notify_userA

Send a notification message to the user via Telegram. Does not wait for a response.

ParametersJSON Schema
NameRequiredDescriptionDefault
messageYesThe notification message to send

TDQS

A4/5.0
Behavior4/5

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

No annotations are provided, so the description carries the behavioral burden. It discloses the key non-blocking trait ('Does not wait for a response'), which is beyond what the schema shows. It could add delivery failure behavior, but for a simple notify tool the core behavior is transparent.

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 short, purposeful sentences. The action and channel are front-loaded, and the distinguishing behavior is stated compactly. No unnecessary words.

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 simple one-parameter tool with no output schema, the description covers the purpose, channel, and behavioral caveat. It is nearly complete; only explicit routing to ask_user is missing, but that gap is already accounted for under usage guidelines.

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 the parameter is already fully documented in the schema. The description adds no parameter-specific semantics beyond what the schema provides, matching the baseline for high coverage.

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?

The description uses a specific verb ('Send'), names the resource ('notification message'), identifies the channel ('via Telegram'), and adds a behavioral qualifier ('Does not wait for a response') that distinguishes it from the sibling ask_user. An agent can tell exactly what this tool does.

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

Usage Guidelines3/5

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

The description implies usage: use this for fire-and-forget notifications where no reply is expected. However, it never explicitly names the alternative (ask_user) or states when to choose it instead, leaving the when-not-to-use guidance to inference.

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. 2 tool updatesv1.0.0
    • First observedask_user
    • First observednotify_user
Deploy Server
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

TDQS

A4.2/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are clearly separated by whether they wait for a reply: ask_user requires an answer, notify_user is fire-and-forget. There is no overlap in their intended use.

Naming Consistency5/5

Both tools follow the same verb_object pattern (ask_user, notify_user), making their behavior predictable and consistent.

Tool Count3/5

With only two tools, the set feels minimal. While it covers the basic interaction modes, two tools is at the lower boundary of what is considered a well-scoped set.

Completeness4/5

The server covers the two fundamental Telegram interaction patterns (interactive question and one-way notification). Some advanced messaging features like media or message editing are absent, but for the stated purpose the core functions are present.

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.
    5 npm
    22
    MIT

  • tsgram-mcp

    areweai
    A
    license
    Not graded
    quality
    D
    maintenance
    Connects Claude Code sessions to Telegram, enabling AI-powered code assistance and file management directly from Telegram chats.
    89
    MIT