Metadata-Version: 2.4
Name: telegram-mcp-kit
Version: 0.1.0
Summary: Telegram Bot API integration via MCP
Author-email: QuocTang <tang.ai.quoc123@gmail.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp[cli]>=1.26.0
Requires-Dist: pydantic-settings>=2.13.1
Description-Content-Type: text/markdown

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

# telegram-mcp

MCP server that exposes the [Telegram Bot API](https://core.telegram.org/bots/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](https://docs.astral.sh/uv/)
- Telegram Bot Token (create via [@BotFather](https://t.me/BotFather))

## Installation

> Get your bot token from [@BotFather](https://t.me/BotFather) on Telegram first.

### Option 1: From PyPI (recommended)

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

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

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

</details>

### Option 2: From GitHub

```bash
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
```

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

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

</details>

### Option 3: From source

```bash
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
```

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

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

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

</details>

### Option 4: Remote SSE (Hugging Face Spaces)

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

1. [Duplicate the Space](https://huggingface.co/spaces/quoctang/telegram-mcp?duplicate=true)
2. In your Space, go to **Settings > Variables** and add `TELEGRAM_BOT_TOKEN`
3. Connect to your Space:

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

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

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

</details>

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

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

See [CONTRIBUTING.md](CONTRIBUTING.md) for how to add new tools.

## License

[MIT](LICENSE)
