# ✈️ Telegram MCP Server

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python Version](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://python.org)
[![MCP Protocol](https://img.shields.io/badge/Protocol-MCP%20Standard-brightgreen.svg)](https://modelcontextprotocol.io)
[![Code Style: Ruff](https://img.shields.io/badge/Code%20Style-Ruff-000000.svg)](https://github.com/astral-sh/ruff)

A generic, production-ready **[Model Context Protocol (MCP)](https://modelcontextprotocol.io/)** 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.

---

## 🛠️ 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](https://t.me/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](https://t.me/userinfobot) or your bot, and save your chat ID.

### 2. Installation

Clone this repository:

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

#### Option A: Using Python Virtual Environment (Standard)

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

Copy and edit configuration:

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

Test that the server runs:

```bash
telegram-mcp --help
```

#### Option B: Using Docker

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

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

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

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

```bash
# 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](LICENSE).