What is Chigwell Telegram Mcp

chigwell_telegram-mcp is a Telegram MCP (Model Context Protocol) server developed using Python, Telethon, and the MCP Python SDK. It allows users to interact with Telegram chats through MCP-compatible hosts.

Use cases

Use cases include building chatbots that respond to user messages, automating notifications in Telegram groups, and integrating Telegram functionalities into desktop applications.

How to use

To use chigwell_telegram-mcp, clone the repository, set up your environment by filling in your Telegram credentials in the .env file, and run the server using the command ‘uv run main.py’. The first time you run it, you will need to authenticate via a code sent to your Telegram client.

Key features

Key features include retrieving a paginated list of Telegram chats, fetching paginated messages from specific chats, and sending messages to designated chats.

Where to use

chigwell_telegram-mcp can be used in various fields such as chatbots, automated messaging systems, and any application requiring interaction with Telegram chats.

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.