telegram-mcp-kit 0.1.0

Telegram Bot API integration via MCP

---

title: telegram-mcp emoji: 🤖 colorFrom: blue colorTo: purple sdk: docker pinned: false

telegram-mcp

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

Features

• 20 tools covering messages, chat management, files/photos, and bot info
• Auto-discovery: add a file to tools/ and your tool is registered automatically
• Runs over stdio (local) or SSE (remote / Docker)

Requirements

• Python >= 3.12
• uv
• Telegram Bot Token (create via @BotFather)

Installation

Get your bot token from @BotFather on Telegram first.

Option 1: From PyPI (recommended)

claude mcp add telegram-mcp \
  -e TELEGRAM_BOT_TOKEN=your-bot-token-here \
  -- uvx telegram-mcp-server

Manual MCP config

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

Option 2: From GitHub

claude mcp add telegram-mcp \
  -e TELEGRAM_BOT_TOKEN=your-bot-token-here \
  -- uvx --from "git+https://github.com/QuocTang/telegram-bot.git#subdirectory=telegram-mcp" telegram-mcp

Manual MCP config

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/QuocTang/telegram-bot.git#subdirectory=telegram-mcp",
        "telegram-mcp"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}

Option 3: From source

git clone https://github.com/QuocTang/telegram-bot.git
cd telegram-bot/telegram-mcp
cp .env.example .env   # add your TELEGRAM_BOT_TOKEN
uv sync

claude mcp add telegram-mcp \
  -- uv run --directory /absolute/path/to/telegram-mcp telegram-mcp

Manual MCP config

{
  "mcpServers": {
    "telegram-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/telegram-mcp",
        "telegram-mcp"
      ]
    }
  }
}

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

Option 4: Remote SSE (Hugging Face Spaces)

Deploy your own instance on HF Spaces — no local installation required.

1. Duplicate the Space
2. In your Space, go to Settings > Variables and add TELEGRAM_BOT_TOKEN
3. Connect to your Space:

claude mcp add telegram-mcp --transport sse \
  https://your-username-telegram-mcp.hf.space/sse

Manual MCP config

{
  "mcpServers": {
    "telegram-mcp": {
      "type": "sse",
      "url": "https://your-username-telegram-mcp.hf.space/sse"
    }
  }
}

Run /mcp inside Claude Code to verify the server is connected.

Tools

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.

Environment variables

Variable	Required	Description
TELEGRAM_BOT_TOKEN	Yes	Token from BotFather
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)

Development

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

See CONTRIBUTING.md for how to add new tools.

License

MIT