Telegram

Telegram MCP Server

A Telegram MCP (Model Context Protocol) server built using Python, Telethon, and MCP Python SDK. This MCP server provides simple tools for interacting with Telegram chats directly through MCP-compatible hosts, such as Claude for Desktop.

Tools Provided

get_chats: Retrieve a paginated list of your Telegram chats.
get_messages: Retrieve paginated messages from a specific chat.
send_message: Send a message to a specific chat.

Requirements

Python 3.10 or higher
Telethon package
MCP Python SDK
UV (optional but recommended)

Installation and Setup

Clone the Repository

1git clone https://github.com/chigwell/telegram-mcp
2cd telegram-mcp

Create Environment File

Copy and rename .env.example to .env and fill it with your Telegram credentials obtained from https://my.telegram.org/apps:

1cp .env.example .env

Your .env file should look like:

1TELEGRAM_API_ID=your_api_id_here
2TELEGRAM_API_HASH=your_api_hash_here
3TELEGRAM_SESSION_NAME=your_session_name

Setup Python Environment

Use uv to set up the Python environment and install dependencies:

1uv venv
2source .venv/bin/activate
3uv add "mcp[cli]" telethon python-dotenv nest_asyncio

Run the Server (First-time Auth)

The first time you run the server, Telethon will prompt you to enter a Telegram authentication code:

1uv run main.py

Authenticate by entering the code sent to your Telegram client. This step is only required once.

Integrating with Claude for Desktop

macOS/Linux

Edit your Claude Desktop configuration:

1nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Add this MCP server configuration:

1{
2    "mcpServers": {
3        "telegram-mcp": {
4            "command": "uv",
5            "args": [
6                "--directory",
7                "/ABSOLUTE_PATH/telegram-mcp",
8                "run",
9                "main.py"
10            ]
11        }
12    }
13}

Ensure you replace /ABSOLUTE_PATH/telegram-mcp with your project's absolute path.

Windows