# Telegram MCP

An MCP (Model Context Protocol) server that exposes Telegram bot actions as tools for LLM clients (e.g. Claude Desktop, Claude Code).

![Telegram MCP screenshot](https://i.ibb.co/hxtQ1Myg/Screenshot-2026-07-31-at-5-36-29-PM.png)

## Requirements

- Python 3.10+
- [`uv`](https://docs.astral.sh/uv/) for dependency management and running the server
- A Telegram bot application with a bot token ([Telegram Bot API](https://core.telegram.org/bots/api))

## Installation

```bash
git clone https://github.com/EncryptMan/telegram-mcp telegram-mcp
cd telegram-mcp
uv sync
```

## Configuration

The server reads its Telegram bot token from the `TELEGRAM_BOT_TOKEN` environment variable.

Add the server to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "telegram": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/absolute/path/to/telegram-mcp",
        "python",
        "/absolute/path/to/telegram-mcp/main.py"
      ],
      "env": {
        "TELEGRAM_BOT_TOKEN": "your-bot-token-here"
      }
    }
  }
}
```

Restart your MCP client after editing the config so it picks up the new server.

### Bot permissions

Make sure the bot is set up with the following, depending on which tools you use:

- **Privacy mode disabled** via [@BotFather](https://t.me/BotFather) if you need `get_updates` to see all messages in a group, not just commands and replies to the bot.
- **Admin rights in the chat/channel** for any moderation or management tool: `ban_chat_member`, `unban_chat_member`, `delete_message`, `pin_chat_message`, `unpin_chat_message`, `set_chat_title`, `set_chat_description`.
- A **webhook URL with a valid HTTPS certificate** if you use `set_webhook` instead of polling with `get_updates`.

## Tools

> Update this list to match what `main.py` actually implements.

| Tool | Description |
|---|---|
| `get_bot_info` | Fetch the bot's own user info |
| `get_webhook_info` / `set_webhook` / `delete_webhook` | Manage the bot's webhook |
| `get_updates` | Poll for new messages/events (alternative to a webhook) |
| `get_my_commands` / `set_my_commands` | Fetch or register the bot's slash commands |
| `send_message` / `edit_message_text` / `delete_message` | Send, edit, or delete a text message |
| `send_photo` / `send_video` / `send_audio` / `send_document` / `send_voice` | Send media to a chat |
| `send_poll` / `stop_poll` | Create a poll or close one and return results |
| `pin_chat_message` / `unpin_chat_message` | Pin or unpin a message |
| `set_message_reaction` | React to a message with an emoji |
| `answer_callback_query` | Respond to an inline keyboard button press |
| `get_chat` | Fetch info about a chat/channel |
| `get_chat_administrators` | List a chat's administrators |
| `get_chat_member` | Get a specific user's membership status in a chat |
| `ban_chat_member` / `unban_chat_member` | Moderation actions |
| `set_chat_title` / `set_chat_description` | Update a chat/channel's title or description |

## Example automations

Some concrete tasks this server can drive, e.g. for a trading-alerts community:

**Alert distribution**
- Push formatted signals to a channel with `send_message`, with a chart via `send_photo`
- Pin the top-priority alert with `pin_chat_message`, unpin it later with `unpin_chat_message`
- Correct a typo or update a price target on a sent alert with `edit_message_text` instead of re-sending

**Community engagement**
- Run a daily sentiment poll with `send_poll`, close it with `stop_poll`, and post the tally with `send_message`
- Auto-react to confirm an alert was received, using `set_message_reaction`
- Send weekly performance recaps as a file with `send_document`

**Interactive bot menus**
- Build inline buttons (e.g. "Mute this ticker"); receive the press via `get_updates`/webhook, acknowledge it with `answer_callback_query`, then reply with `send_message`
- Register commands like `/subscribe`, `/mute`, `/stats` with `set_my_commands` and drive their logic off `get_updates`

**Moderation & access control**
- Ban a user spamming or scraping paid content with `ban_chat_member`, reverse with `unban_chat_member`
- Gate sensitive commands by checking `get_chat_administrators` or `get_chat_member` first
- Remove spam or leaked-content messages with `delete_message`

**Housekeeping / setup**
- Rotate the channel name/description with `set_chat_title` / `set_chat_description`
- Switch between polling (`get_updates`) and push delivery (`set_webhook`/`get_webhook_info`) when moving from local dev to hosted
- Sanity-check the bot's identity and permissions with `get_bot_info` before deploying a new flow

## Running standalone

```bash
uv run --project /absolute/path/to/telegram-mcp python /absolute/path/to/telegram-mcp/main.py
```

The server communicates over stdio, so it's meant to be launched by an MCP client rather than run interactively.

## Security notes

- Never commit your `TELEGRAM_BOT_TOKEN` — keep it in your MCP client config or a local `.env` file that's gitignored.
- Scope the bot's admin rights in each chat to only what these tools need; avoid granting full admin unless required.

## License

Add a license of your choice (MIT, Apache-2.0, etc.).