Telegram MCP server

This server allows you to connect Claude to your Telegram account, enabling it to read and send messages on your behalf. With this integration, Claude can interact with your Telegram chats, helping you manage conversations and respond to messages.

Setup Guide

Getting Telegram API Credentials

1. Visit https://my.telegram.org/apps
2. Log in and create a new application
3. Save your API ID and API Hash for later use

Installation

# Clone the repository
git clone https://github.com/alexandertsai/mcp-telegram
cd mcp-telegram

# Set up Python environment
pip install uv
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv sync

Configuration

# Copy the example configuration file
cp .env.example .env

# Edit .env and add your API credentials:
# TELEGRAM_API_ID=your_api_id_here
# TELEGRAM_API_HASH=your_api_hash_here

Authentication

cd src/mcp_telegram
python telethon_auth.py

During the authentication process:

• Enter your phone number with country code (e.g., +1234567890)
• Enter the verification code sent to your Telegram
• If you have two-factor authentication, enter your 2FA password

Adding to Claude Desktop

Locate your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "telegram": {
      "command": "/path/to/python",
      "args": ["/path/to/mcp-telegram/src/mcp_telegram/main.py"]
    }
  }
}

To find the correct paths:

• For Python: Run which python (Mac) or where.exe python (Windows)
• For main.py: Right-click the file and select "Copy Path"

Remember to restart Claude Desktop after making these changes.

Using the MCP Server

Once properly set up, you can ask Claude to perform the following actions:

• "Check my Telegram messages"
• "Send a message to [contact name]"
• "What are my unread chats?"
• "Reply to the last message from [contact name]"

Available Tools

Getting Chats

Claude can list your Telegram chats with:

• Chat names, IDs, and unread message counts
• Pagination for browsing through multiple chats

Reading Messages

Claude can fetch and read messages from any chat and will automatically mark them as read.

Marking Messages as Read

You can ask Claude to mark all unread messages in a specific chat as read.

Sending Messages

Claude can send messages to any chat and supports replying to specific messages.

Customizing Conversation Style

Create a file at src/mcp_telegram/convostyle.txt with instructions about your texting style:

I text casually with friends, formally with work contacts.
I use emojis sparingly and prefer short messages.

This helps Claude analyze your chat style and match your texting patterns when responding.

Troubleshooting

Authentication Problems

If you encounter authentication issues:

1. Verify your API credentials in the .env file
2. Remove the TELEGRAM_SESSION_STRING line from .env
3. Run python telethon_auth.py again to re-authenticate

Common Error Messages

• "Please set TELEGRAM_API_ID and TELEGRAM_API_HASH": This indicates missing credentials in your .env file
• "Session string is invalid or expired": You need to re-authenticate
• 2FA password not displaying when typed: This is normal security behavior - continue typing your password

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "telegram" '{"command":"/your/path/to/python3","args":["/full/path/to/mcp-telegram/main.py"],"env":{"TELEGRAM_API_ID":"your_api_id_here","TELEGRAM_API_HASH":"your_api_hash_here","TELEGRAM_PHONE":"+65945678900"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "telegram": {
            "command": "/your/path/to/python3",
            "args": [
                "/full/path/to/mcp-telegram/main.py"
            ],
            "env": {
                "TELEGRAM_API_ID": "your_api_id_here",
                "TELEGRAM_API_HASH": "your_api_hash_here",
                "TELEGRAM_PHONE": "+65945678900"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "telegram": {
            "command": "/your/path/to/python3",
            "args": [
                "/full/path/to/mcp-telegram/main.py"
            ],
            "env": {
                "TELEGRAM_API_ID": "your_api_id_here",
                "TELEGRAM_API_HASH": "your_api_hash_here",
                "TELEGRAM_PHONE": "+65945678900"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect