Telegram MCP Server

This is a simple MCP server that lets Claude access your Telegram account to read and send messages.

Functions

**`get_chats`**: Get a list of your Telegram chats

**`send_message`**: Send a message to a chat

**`get_message`**: Gets messages from a chat and prints the unread messages

**`mark_messages_read`**: Mark messages as read

**`get_conversation_context`**: Gets past 20 messages and reads `convostyle.txt` to determine an appropriate reply

Setup

Recommended set up

Step 1: Get Your Telegram API Credentials

Go to [https://my.telegram.org/apps](https://my.telegram.org/apps)

Log in and create an application (or use an existing one) Note: It doesn't matter what kind of application - just create anything... make sure to select "web" under the type.

Note down your **API ID** and **API Hash**

Step 2: Set Up Python Environment

Install the required packages (open your terminal to do this. command+space on mac and key in 'terminal' or on windows hit the windows key and key in 'terminal'. Copy and paste the code into the terminal line by line). Ensure you have installed Git beforehand.

Set up the virtual environment. Use `pip3` instead if applicable.

Step 3: Add IDs

**For Mac (bash):**

In the virtual environment, run the following:

Check to see if they have been exported with `printenv` in terminal.

**For Windows (Powershell):**

In the virtual environment, run the following. Make sure to include the quotation marks otherwise powershell may struggle:

Check to see if they have been exported with `gci env:` in powershell.

Step 4: Run authentication

Run this to authenticate. If you have 2FA, when typing in your password you will not see any text appear in the terminal. This is normal! Try not to make a typo during 2FA - it makes you restart the entire process if you do... Use `python` or `python3` depending on which you have installed.:

You'll be asked for:

Your phone number (in international format with +) (do not leave any spaces)

The code Telegram sends to your account

Your 2FA password (if enabled)

This creates a session file in your home directory so you don't need to authenticate again.

Step 5: Add to Claude Desktop

Edit your Claude Desktop configuration:

Open Claude desktop, go to settings (cmd+,), click on Developer and then Edit Config. Edit the claude)desktop_config.json file. Make sure developer mode is enabled.

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

Add this to your config (replace with your actual credentials). Press command+s to save. :

**main.py:** To get the full path, go to your IDE or desktop, find the file, right click on it, and click "COPY PATH".

**python:** Run `where.exe python` (Windows) or `where python` (Mac) in your terminal to get the full path (replace with `python3` if needed). If on Windows, you may need to replace the backslashes in your path with forward slash because of JSON formatting (ctrl+f "\\", replace all (ctrl + h) with "/").

VERY IMPORTANT:

Use the full absolute path to both Python and the main.py script

Replace API credentials with your actual values from Step 1

Set your phone number in international format

Step 6 (optional):

Feel free to configure `convostyle.txt` in `src/mcp_telegram` if you want the chatbot to respond and sound like you.

That's It!

Restart Claude Desktop (quit and reopen), and you can now ask Claude to:

Show your recent Telegram chats

Read messages from specific chats

Mark certain messages as "read"

Send messages to your contacts or groups while sounding natural

Make sure to include the word "Telegram" when asking Claude a prompt or it might not understand. For example, "Claude do I have any unread telegram messages?"

Customisation

You can go under Claude Desktop -> click on your user then settings in the bottom left -> configure your personal preferences to get more tailored responses. For example "When using MCP to check Telegram, ignore channels".

Pesky troubleshooting

While in the virtual environment, try running:

Then terminate your session files with (just copy and paste the path of the files with rm in front)

Try step 3 again.

Telegram