Telegram MCP Server

Connect Claude to your Telegram account to read and send messages.

Features

Available Tools

get_chats - List your Telegram chats
- Returns paginated list with chat names, IDs, and unread counts
- For page 1, just provide page number
- For subsequent pages, use the pagination parameters from the previous response
get_messages - Read messages from a specific chat
- Fetches paginated message history
- Automatically marks messages as read
mark_messages_read - Mark all unread messages in a chat as read
send_message - Send messages to any chat
- Supports replying to specific messages
get_conversation_context - Analyze chat style for natural responses
- Reads your conversation style guide from convostyle.txt
- Helps Claude match your texting patterns

Setup Guide

Step 1: Get Telegram API Credentials

Go to https://my.telegram.org/apps
Log in and create an application
Save your API ID and API Hash

Step 2: Install

# 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

Step 3: Configure

# Copy the example 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

Step 4: Authenticate

cd src/mcp_telegram
python telethon_auth.py

Follow the prompts:

Enter your phone number (with country code, e.g., +1234567890)
Enter the code sent to your Telegram
Enter your 2FA password if you have one

Step 5: Add to Claude Desktop

Find your Claude Desktop config file:

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

Add this configuration:

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

To find paths:

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

Restart Claude Desktop.

Usage

After setup, you can ask Claude to:

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

Style Guide (Optional)

Create src/mcp_telegram/convostyle.txt to help Claude match your texting style:

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

Troubleshooting

Authentication Issues

If authentication fails:

Check your API credentials in .env
Remove the TELEGRAM_SESSION_STRING line from .env
Run python telethon_auth.py again

Common Errors

"Please set TELEGRAM_API_ID and TELEGRAM_API_HASH": Missing .env file or credentials
"Session string is invalid or expired": Re-run authentication
2FA password not showing: This is normal - keep typing

Requirements

Python 3.10+
Claude Desktop
Telegram account

License

Apache 2.0

This server cannot be installed

security - not tested

license - permissive license

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

A simple MCP server that allows Claude to access your Telegram account to read and send messages on your behalf.

Related MCP Servers

MCP-Communicator-Telegram
qpd-v
-
security
F
license
-
quality
An MCP server that enables communication with users through Telegram. This server provides a tool to ask questions to users and receive their responses via a Telegram bot.
Last updated -
1
38
JavaScript
Twitter MCP Server
EnesCinr
A
security
A
license
A
quality
An MCP server that enables Claude to interact with Twitter, allowing for posting tweets and searching Twitter content.
Last updated -
2
773
274
TypeScript
MIT License
Telegram MCP Server
chigwell
-
security
A
license
-
quality
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.
Last updated -
280
Python
Apache 2.0
Mattermost MCP Server
pvev
-
security
F
license
-
quality
An MCP server that enables Claude and other MCP clients to interact with Mattermost workspaces, providing channel management, messaging capabilities, and topic monitoring functionality.
Last updated -
14
TypeScript

View all related MCP servers

Telegram MCP Server