telegram-mcp

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

git clone https://github.com/chigwell/telegram-mcp
cd 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:

cp .env.example .env

Your .env file should look like:

TELEGRAM_API_ID=your_api_id_here
TELEGRAM_API_HASH=your_api_hash_here
TELEGRAM_SESSION_NAME=your_session_name

Setup Python Environment

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

uv venv
source .venv/bin/activate
uv 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:

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

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

Add this MCP server configuration:

{
    "mcpServers": {
        "telegram-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE_PATH/telegram-mcp",
                "run",
                "main.py"
            ]
        }
    }
}

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

Windows

Edit your Claude Desktop configuration:

nano $env:AppData\Claude\claude_desktop_config.json

Add this MCP server configuration:

{
    "mcpServers": {
        "telegram-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\ABSOLUTE_PATH\\telegram-mcp",
                "run",
                "main.py"
            ]
        }
    }
}

Ensure you replace C:\ABSOLUTE_PATH\telegram-mcp with your project's absolute path.

Usage

Once integrated, your Telegram tools (get_chats, get_messages, and send_message) will become available within the Claude for Desktop UI or any other MCP-compatible client.

License

This project is licensed under the Apache 2.0 License.