Skip to main content
Glama
telegram-mcp-kit

telegram-mcp-kit

by QuocTang

🚀 telegram-mcp-kit

MCP server that exposes the Telegram Bot API as tools for Claude Code (or any MCP client).

License: MIT Python Version uv

Table of Contents


Related MCP server: Telegram MCP Server

🚀 Quick Start

Get your bot token from @BotFather on Telegram. Once the server is configured, you can run /mcp inside Claude Code to verify it is connected.

🛠️ Installation

Get your bot token from @BotFather on Telegram first.

claude mcp add telegram-mcp-kit \
  -e TELEGRAM_BOT_TOKEN=your-bot-token-here \
  -e TELEGRAM_CHAT_ID=your-chat-id \
  -- uvx telegram-mcp-kit
{
  "mcpServers": {
    "telegram-mcp-kit": {
      "command": "uvx",
      "args": ["telegram-mcp-kit"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here",
        "TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

Option 2: From GitHub

claude mcp add telegram-mcp-kit \
  -e TELEGRAM_BOT_TOKEN=your-bot-token-here \
  -e TELEGRAM_CHAT_ID=your-chat-id \
  -- uvx --from "git+https://github.com/QuocTang/telegram-mcp-kit.git" telegram-mcp-kit
{
  "mcpServers": {
    "telegram-mcp-kit": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/QuocTang/telegram-mcp-kit.git",
        "telegram-mcp-kit"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here",
        "TELEGRAM_CHAT_ID": "your-chat-id"
      }
    }
  }
}

Option 3: From source

git clone https://github.com/QuocTang/telegram-mcp-kit.git
cd telegram-mcp-kit
cp .env.example .env   # add your TELEGRAM_BOT_TOKEN
uv sync
claude mcp add telegram-mcp-kit \
  -- uv run --directory /absolute/path/to/telegram-mcp-kit telegram-mcp-kit
{
  "mcpServers": {
    "telegram-mcp-kit": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/telegram-mcp-kit",
        "telegram-mcp-kit"
      ]
    }
  }
}

With this option, TELEGRAM_BOT_TOKEN is read from the .env file inside the project directory.

Environment variables

Variable

Required

Description

TELEGRAM_BOT_TOKEN

Yes

Token from BotFather

TELEGRAM_CHAT_ID

No

Default chat ID (if set, chat_id can be omitted in tool calls)

MCP_TRANSPORT

No

stdio (default) or sse

MCP_HOST

No

Bind host (default 127.0.0.1)

MCP_PORT

No

Bind port (default 8000)

HTTP_TIMEOUT

No

Telegram API timeout in seconds (default 30)

📦 Features

🚀 Feature

📝 Description

🛠️ 20+ Tools

Comprehensive coverage for messages, chat management, files/photos, and bot info.

🔍 Auto-discovery

Simply add a Python file to the tools/ folder and it registers automatically.

📡 Flexible Transport

Works seamlessly over stdio (for local clients) or SSE (remote/Docker).

Tools List

Messages

Tool

Description

send_message

Send a text message (Markdown/HTML)

edit_message

Edit an existing message

delete_message

Delete a message

forward_message

Forward a message between chats

Updates

Tool

Description

get_updates

Fetch recent messages/updates the bot received

Chat management

Tool

Description

get_chat_info

Get chat metadata (name, type, description)

get_chat_member_count

Count members

get_chat_admins

List administrators

ban_member

Ban a user

unban_member

Unban a user

set_chat_title

Change group/channel title

set_chat_description

Change group/channel description

pin_message

Pin a message

unpin_message

Unpin a message

Files & photos

Tool

Description

send_photo

Send a photo by URL or file_id

send_photo_file

Send a local photo file

send_document

Send a document by URL or file_id

send_document_file

Send a local file as document

get_file_info

Get file metadata + download link

Bot

Tool

Description

get_bot_info

Get bot name, username, etc.

🤝 How to Contribute

We welcome contributions! Please follow these steps:

  1. Fork the repository.

  2. Create a new branch for your feature.

  3. Submit a Pull Request.

See CONTRIBUTING.md for how to add new tools.

Development

uv sync                        # install all deps (including dev)
uv run pytest -v               # run tests
uv run ruff check src/ tests/  # lint

💬 Community & Support

If this repository saves you time, please star the repository!

👥 Repo Contributors

Made with contrib.rocks.

⚖️ License

MIT License. See LICENSE for details.

🌟 Star History

Star History Chart

Available Tools

20 tools
ban_memberA

Ban a user from a chat.

Args: user_id: User ID to ban chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)

Inputs: user_id (required), chat_id. Returns: result

delete_messageB

Delete a message from a chat.

Args: message_id: ID of the message to delete chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)

Inputs: message_id (required), chat_id. Returns: result

edit_messageA

Edit an existing message.

Args: message_id: ID of the message to edit text: New text for the message chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) parse_mode: "Markdown", "MarkdownV2", or "HTML" (optional)

Inputs: message_id (required), text (required), chat_id, parse_mode. Returns: result

forward_messageB

Forward a message from one chat to another.

Args: from_chat_id: Source chat ID message_id: ID of the message to forward chat_id: Target chat ID (uses TELEGRAM_CHAT_ID if omitted)

Inputs: from_chat_id (required), message_id (required), chat_id. Returns: result

get_bot_infoA

Get information about the bot (name, username, etc.).

Inputs: no named parameters. Returns: result

get_chat_adminsB

Get list of administrators in a chat.

Args: chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)

Inputs: chat_id. Returns: result

get_chat_infoA

Get information about a chat (group, channel, or private chat).

Args: chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)

Inputs: chat_id. Returns: result

get_chat_member_countA

Get the number of members in a chat.

Args: chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)

Inputs: chat_id. Returns: result

get_file_infoA

Get file info and download link from Telegram.

Args: file_id: Telegram file ID (from received messages)

Inputs: file_id (required). Returns: result

get_updatesA

Get recent messages/updates received by the bot.

Args: offset: Update ID offset (to get updates after a specific ID) limit: Maximum number of updates to return (1-100, default 100)

Inputs: offset, limit. Returns: result

pin_messageA

Pin a message in a chat.

Args: message_id: ID of the message to pin chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) silent: Pin without notification (default False)

Inputs: message_id (required), chat_id, silent. Returns: result

send_documentA

Send a document/file to a chat.

Args: document: Document URL or file_id chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) caption: Document caption (optional) parse_mode: "Markdown", "MarkdownV2", or "HTML" for caption (optional)

Inputs: document (required), chat_id, caption, parse_mode. Returns: result

send_document_fileA

Send a local file as a document to a chat.

Args: file_path: Absolute path to the file on disk chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) caption: Document caption (optional) parse_mode: "Markdown", "MarkdownV2", or "HTML" for caption (optional)

Inputs: file_path (required), chat_id, caption, parse_mode. Returns: result

send_messageA

Send a text message to a Telegram chat.

Args: text: Message text (supports Markdown/HTML based on parse_mode) chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) parse_mode: "Markdown", "MarkdownV2", or "HTML" (optional) reply_to_message_id: ID of message to reply to (optional)

Inputs: text (required), chat_id, parse_mode, reply_to_message_id. Returns: result

send_photoA

Send a photo to a chat.

Args: photo: Photo URL or file_id chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) caption: Photo caption (optional) parse_mode: "Markdown", "MarkdownV2", or "HTML" for caption (optional)

Inputs: photo (required), chat_id, caption, parse_mode. Returns: result

send_photo_fileA

Send a local photo file to a chat.

Args: file_path: Absolute path to the photo file on disk chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) caption: Photo caption (optional) parse_mode: "Markdown", "MarkdownV2", or "HTML" for caption (optional)

Inputs: file_path (required), chat_id, caption, parse_mode. Returns: result

set_chat_descriptionA

Change the description of a chat (group/channel).

Args: description: New description (0-255 characters) chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)

Inputs: description (required), chat_id. Returns: result

set_chat_titleA

Change the title of a chat (group/channel).

Args: title: New chat title (1-128 characters) chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)

Inputs: title (required), chat_id. Returns: result

unban_memberA

Unban a user from a chat.

Args: user_id: User ID to unban chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted)

Inputs: user_id (required), chat_id. Returns: result

unpin_messageB

Unpin a message in a chat.

Args: chat_id: Chat ID or @channel_username (uses TELEGRAM_CHAT_ID if omitted) message_id: ID of message to unpin (optional, unpins most recent if not specified)

Inputs: chat_id, message_id. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 20 tools

    Disambiguation5/5

    All tools have distinct purposes with clear separation; similar pairs like send_document/send_document_file and send_photo/send_photo_file are differentiated by source type (URL/file_id vs local path).

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., ban_member, get_chat_info, send_photo_file).

    Tool Count4/5

    20 tools is on the higher end but covers core Telegram bot functionalities without being excessive. Each tool is justified.

    Completeness3/5

    Covers common messaging, moderation, and info retrieval but lacks support for sending stickers, audio, video, location, polls, and other media types, which are notable gaps for a full-featured Telegram toolset.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables interaction with the Telegram Bot API via the Model Context Protocol to send, edit, and delete messages, photos, and videos. It allows Claude to manage Telegram communications and fetch bot updates through natural language commands.
      58 npm
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude to send messages, media, and manage Telegram chat messages through a Telegram bot, including sending photos, documents, and editing or deleting messages.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes Telegram Bot API operations as MCP tools, enabling managing messages, chats, and forum topics via a FastMCP server.
      -