🚀 telegram-mcp-kit

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

Table of Contents

• 🚀 Quick Start
• 🛠️ Installation
• 📦 Features
• 🤝 How to Contribute
• 💬 Community & Support
• 👥 Repo Contributors
• ⚖️ License
• 🌟 Star History

---

🚀 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.

Option 1: From PyPI (recommended)

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

<details> <summary>Manual MCP config</summary>

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

</details>

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

<details> <summary>Manual MCP config</summary>

{
  "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"
      }
    }
  }
}

</details>

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

<details> <summary>Manual MCP config</summary>

{
  "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.

</details>

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

<a href="https://github.com/QuocTang/telegram-mcp-kit/graphs/contributors"> <img src="https://contrib.rocks/image?repo=QuocTang/telegram-mcp-kit" alt="Repository contributors" /> </a>

Made with contrib.rocks.

⚖️ License

MIT License. See LICENSE for details.

🌟 Star History