Skip to main content
Glama
Sign In
Telegram MCP Server

Telegram MCP Server

by ivantelix
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

✈️ Telegram MCP Server

License: MIT Python Version MCP Protocol Code Style: Ruff

A generic, production-ready Model Context Protocol (MCP) server for the Telegram Bot API.

This server allows AI assistants (such as Claude Desktop, Antigravity IDE, Cursor, Continue, or any custom MCP client) to interact directly with Telegram: sending formatted messages, uploading files and images, administering chats, broadcasting alerts, and reading incoming messages.

✨ Features

  • 💬 Messaging: Send text with rich formatting (HTML, MarkdownV2, Markdown), silent delivery, link preview toggles, and reply chaining.

  • 🖼️ Media & File Uploads: Send photos, documents (PDF, zip, code), audio tracks, and voice notes (.ogg) from either local file paths or remote URLs.

  • 📊 Polls & Locations: Create native polls (anonymous/multiple answers) and send geographic coordinates.

  • 👥 Chat & Channel Management: Inspect chat info, member counts, administrator lists, pin/unpin messages, and delete messages.

  • 📥 Incoming Updates: Read incoming messages and user interactions with polling.

  • 🛡️ Zero Token Risk: Built on the official Telegram Bot API (no phone numbers or user sessions required).

  • 🌐 Self-Hosted API Support: Compatible with self-hosted Telegram Local Bot API servers (to support files up to 2,000 MB).

  • 🧩 MCP Resources & Prompts: Includes status inspection resources and pre-configured prompt templates for alerts and summaries.

Related MCP server: Telegram Bot MCP Server

🛠️ Available MCP Tools

Tool

Description

Key Parameters

telegram_get_me

Check bot identity, username, and token validity

None

telegram_send_message

Send formatted text message to user/group/channel

text, chat_id (opt), parse_mode, reply_to_message_id

telegram_send_photo

Send photo via local path or URL

photo, caption, chat_id (opt)

telegram_send_document

Send document/file (PDF, code, zip)

document, caption, chat_id (opt)

telegram_send_audio

Send audio track with title and performer

audio, title, performer, caption

telegram_send_voice

Send voice note (.ogg OPUS)

voice, caption, chat_id (opt)

telegram_send_location

Send geographic map coordinates

latitude, longitude, chat_id (opt)

telegram_send_poll

Create a native Telegram poll

question, options, is_anonymous

telegram_forward_message

Forward a message between chats

from_chat_id, message_id, chat_id (opt)

telegram_get_chat

Inspect user/group/channel metadata

chat_id (opt)

telegram_get_chat_member_count

Get total member count

chat_id (opt)

telegram_get_chat_administrators

Get list of admins in a chat

chat_id (opt)

telegram_pin_chat_message

Pin a message in a chat

message_id, chat_id (opt)

telegram_unpin_chat_message

Unpin one or all messages

message_id (opt), chat_id (opt)

telegram_delete_message

Delete a message from a chat

message_id, chat_id (opt)

telegram_get_updates

Poll incoming updates and messages

offset, limit, timeout

💡 Tip: If TELEGRAM_DEFAULT_CHAT_ID is set in your environment, all tools can be called without supplying chat_id.

🚀 Quick Start

1. Prerequisites

  1. Open Telegram and message @BotFather.

  2. Run /newbot and follow instructions to get your Bot Token (e.g. 123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ).

  3. (Optional) Get your Chat ID by messaging @userinfobot or your bot, and save your chat ID.

2. Installation

Clone this repository:

git clone https://github.com/your-username/telegram-mcp.git
cd telegram-mcp

Option A: Using Python Virtual Environment (Standard)

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Copy and edit configuration:

cp .env.example .env
# Edit .env with your TELEGRAM_BOT_TOKEN and optional TELEGRAM_DEFAULT_CHAT_ID

Test that the server runs:

telegram-mcp --help

Option B: Using Docker

# Copy and configure your environment
cp .env.example .env

# Build and run
docker compose up -d

⚙️ Configuration

Set these environment variables in .env or in your MCP client configuration:

Variable

Required

Default

Description

TELEGRAM_BOT_TOKEN

Yes

-

Bot token from @BotFather

TELEGRAM_DEFAULT_CHAT_ID

No

""

Default chat ID to use if omitted in tool calls

TELEGRAM_DEFAULT_PARSE_MODE

No

"HTML"

Default parse mode: HTML, MarkdownV2, Markdown

TELEGRAM_API_BASE_URL

No

"https://api.telegram.org"

Custom Telegram Bot API URL for self-hosted instances

TELEGRAM_REQUEST_TIMEOUT

No

30.0

Timeout in seconds for HTTP requests

LOG_LEVEL

No

"INFO"

Logging level (DEBUG, INFO, WARNING, ERROR)

🔌 Connecting to MCP Clients

Claude Desktop

Edit your claude_desktop_config.json:

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

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

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

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
      "args": [
        "-m",
        "telegram_mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN_HERE",
        "TELEGRAM_DEFAULT_CHAT_ID": "YOUR_CHAT_ID_HERE"
      }
    }
  }
}

Antigravity IDE

Add to your ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
      "args": [
        "-m",
        "telegram_mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN_HERE",
        "TELEGRAM_DEFAULT_CHAT_ID": "YOUR_CHAT_ID_HERE"
      }
    }
  }
}

Cursor

In .cursor/mcp.json or Cursor Settings -> MCP Servers:

{
  "mcpServers": {
    "telegram": {
      "command": "/absolute/path/to/telegram-mcp/.venv/bin/python",
      "args": ["-m", "telegram_mcp"],
      "env": {
        "TELEGRAM_BOT_TOKEN": "YOUR_BOT_TOKEN_HERE"
      }
    }
  }
}

🧪 Development & Testing

Run tests with pytest:

# Run test suite
pytest -v

# Run linting check
ruff check .

# Fix auto-fixable lint issues
ruff check --fix .

🤝 Contributing

Contributions are welcome! Feel free to:

  1. Fork the repository.

  2. Create a feature branch (git checkout -b feature/amazing-feature).

  3. Commit your changes (git commit -m 'Add amazing feature').

  4. Push to the branch (git push origin feature/amazing-feature).

  5. Open a Pull Request.

📄 License

This project is licensed under the MIT License.

Available Tools

16 tools
telegram_delete_messageB

Delete a message from a chat.

:param message_id: Identifier of the message to delete. :param chat_id: Target chat identifier. :return: Status string indicating success.

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

telegram_forward_messageA

Forward an existing message of any type from one chat to another.

:param from_chat_id: Unique identifier for chat where original message was sent. :param message_id: Message identifier in the chat specified in from_chat_id. :param chat_id: Destination chat identifier. Defaults to TELEGRAM_DEFAULT_CHAT_ID. :param disable_notification: Forward message silently. :return: JSON formatted forwarded Message object.

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

telegram_get_chatB

Get detailed information about a chat (private user, group, supergroup, or channel). Returns title, username, description, invite link, active photo, etc.

:param chat_id: Unique identifier for target chat or @channelusername. :return: JSON formatted Telegram Chat object.

Inputs: chat_id. Returns: result

telegram_get_chat_administratorsB

Get a list of administrators in a chat/group/channel.

:param chat_id: Target chat identifier. :return: JSON formatted list of ChatMember objects representing administrators.

Inputs: chat_id. Returns: result

telegram_get_chat_member_countB

Get the total number of members in a group, supergroup, or channel.

:param chat_id: Target chat identifier. :return: Member count integer formatted as string.

Inputs: chat_id. Returns: result

telegram_get_meA

Get current bot identity and configuration status. Tests bot token validity and returns bot id, username, first name, and permissions.

Inputs: no named parameters. Returns: result

telegram_get_updatesA

Retrieve incoming updates (messages, reactions, etc.) sent to the bot. Useful to read incoming user messages or inspect user/group chat IDs.

:param offset: Identifier of the first update to be returned. :param limit: Limits the number of updates to be retrieved (1-100, default 10). :param timeout: Timeout in seconds for short/long polling (0 for immediate response). :return: JSON array of Telegram Update objects.

Inputs: limit, offset, timeout. Returns: result

telegram_pin_chat_messageA

Pin a message in a group, supergroup, or channel.

:param message_id: Identifier of a message to pin. :param chat_id: Target chat identifier. :param disable_notification: Pin silently without notifying chat members. :return: Status string indicating success.

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

telegram_send_audioA

Send an audio file (.mp3, .m4a, etc.) to a chat.

:param audio: Local file path on disk or HTTP/HTTPS URL. :param caption: Audio caption. :param title: Track name. :param performer: Performer / artist name. :param chat_id: Target chat identifier. :param parse_mode: Caption parse mode. :param disable_notification: Send silently. :return: JSON formatted Telegram Message object.

Inputs: audio (required), title, caption, chat_id, +3 more. Returns: result

telegram_send_documentA

Send a general file or document (PDF, ZIP, source code, text file, etc.).

:param document: Local file path on disk (e.g. '/path/to/report.pdf') OR a public HTTP/HTTPS URL. :param caption: Optional document caption (0-1024 characters). :param chat_id: Target chat identifier (or @channelusername). :param parse_mode: Formatting for caption ('HTML', 'MarkdownV2', etc.). :param disable_notification: Send silently. :return: JSON formatted Telegram Message object.

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

telegram_send_locationB

Send a point on the map (geographic coordinates).

:param latitude: Latitude of the location. :param longitude: Longitude of the location. :param chat_id: Target chat identifier. :param disable_notification: Send silently. :return: JSON formatted Telegram Message object.

Inputs: latitude (required), longitude (required), chat_id, disable_notification. Returns: result

telegram_send_messageA

Send a text message to a Telegram chat, group, or channel.

:param text: Text of the message to be sent (up to 4096 characters). :param chat_id: Unique identifier for target chat, group, or channel username (@channelusername). If omitted, uses TELEGRAM_DEFAULT_CHAT_ID if set. :param parse_mode: Formatting mode for message text ('HTML', 'MarkdownV2', 'Markdown', or None). :param disable_web_page_preview: Disables link previews for links in this message. :param disable_notification: Sends the message silently without sound. :param reply_to_message_id: If the message is a reply, ID of the original message. :return: JSON formatted Telegram Message object.

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

telegram_send_photoA

Send a photo/image to a Telegram chat.

:param photo: Local file path on disk (e.g. '/path/to/image.png') OR a public HTTP/HTTPS URL. :param caption: Optional photo caption (0-1024 characters). :param chat_id: Unique identifier for target chat (or @channelusername). :param parse_mode: Formatting for caption ('HTML', 'MarkdownV2', 'Markdown', or None). :param disable_notification: Send silently without notification sound. :return: JSON formatted Telegram Message object.

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

telegram_send_pollA

Send a native poll to a chat or channel.

:param question: Poll question (1-300 characters). :param options: List of 2 to 10 answer options (each 1-100 characters). :param chat_id: Target chat identifier. :param is_anonymous: True if poll should be anonymous, False for public voters. :param allows_multiple_answers: True if poll allows multiple options to be checked. :return: JSON formatted Telegram Message object containing the Poll.

Inputs: options (required), question (required), chat_id, is_anonymous, +1 more. Returns: result

telegram_send_voiceA

Send a voice note (.ogg encoded with OPUS) to a chat.

:param voice: Local file path on disk or HTTP/HTTPS URL. :param caption: Voice message caption. :param chat_id: Target chat identifier. :param parse_mode: Caption parse mode. :param disable_notification: Send silently. :return: JSON formatted Telegram Message object.

Inputs: voice (required), caption, chat_id, parse_mode, +1 more. Returns: result

telegram_unpin_chat_messageA

Unpin a specific message or all messages in a chat.

:param message_id: Identifier of message to unpin. If None, unpins all pinned messages. :param chat_id: Target chat identifier. :return: Status string indicating success.

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…

    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

    A3.7/5.0

    Scored across 16 tools

    Disambiguation5/5

    Every tool targets a distinct action/resource: get_me identifies the bot, get_chat retrieves chat metadata, and the send_* variants each handle a specific media type. Pin/unpin/delete message are clearly separate operations, and get_chat_member_count vs get_chat_administrators are well-differentiated despite both being chat info queries.

    Naming Consistency5/5

    All tools use a consistent telegram_verb_noun pattern (telegram_send_message, telegram_get_chat, telegram_pin_chat_message). The naming convention is uniform throughout, making the tool set predictable and easy to navigate.

    Tool Count4/5

    At 16 tools, the server is just above the typical well-scoped range, but the count is reasonable given the breadth of Telegram messaging and chat admin operations. The send_* media variants each earn their place, though a few could arguably be consolidated.

    Completeness3/5

    Core messaging workflows are covered: send, forward, delete, pin, unpin, plus chat info and member retrieval. However, notable gaps exist such as edit_message, send_video/contact/sticker, get_chat_member, and leave_chat, which agents would likely need for fuller Telegram bot interactions.

    Resources

    Related MCP Connectors

    Related MCP Servers