Telegram MCP Server

Apache 2.0
8
  • Apple
  • Linux

Integrations

  • Enables interaction with Telegram chats, allowing users to retrieve lists of chats, fetch message history, and send messages directly through the Telegram platform.

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

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.

-
security - not tested
A
license - permissive license
-
quality - not tested

A server that enables interaction with Telegram chats directly through MCP-compatible hosts like Claude for Desktop, providing tools to retrieve chats, get messages, and send messages.

  1. Tools Provided
    1. Requirements
      1. Installation and Setup
        1. Clone the Repository
        2. Create Environment File
        3. Setup Python Environment
        4. Run the Server (First-time Auth)
      2. Integrating with Claude for Desktop
        1. macOS/Linux
        2. Windows
      3. Usage
        1. License