Telegram MCP Server

Apache 2.0
4
  • Apple

Integrations

  • Allows Claude to access a Telegram account to read chats, view messages, send messages, mark messages as read, and retrieve conversation context to formulate natural-sounding replies.

Telegram MCP Server

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

Functions

  1. get_chats: Get a list of your Telegram chats
  2. send_message: Send a message to a chat
  3. get_message: Gets messages from a chat and prints the unread messages
  4. mark_messages_read: Mark messages as read
  5. get_conversation_context: Gets past 20 messages and reads convostyle.txt to determine an appropriate reply

Setup

Step 1: Get Your Telegram API Credentials

  1. Go to https://my.telegram.org/apps
  2. 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.
  3. 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.

# Clone the repository within your desired directory (if you haven't already) git clone https://github.com/alexandertsai/mcp-telegram cd mcp-telegram

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

# Set up virtual environment pip install uv uv venv source .venv/bin/activate # .venv\Scripts\activate for windows uv add mcp-sdk telethon python-dotenv nest_asyncio

Step 3: Add IDs

For Mac (bash):

In the virtual environment, run the following:

export TELEGRAM_PHONE=phone number with country code and no spaces export TELEGRAM_API_ID=api_id export TELEGRAM_API_HASH=api_hash

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:

$env:TELEGRAM_PHONE="phone number with country code and no spaces" $env:TELEGRAM_API_ID="api_id" $env:TELEGRAM_API_HASH="api_hash"

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.:

cd src/mcp_telegram python3 telethon_auth.py

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. :

"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" } } }

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:

  1. Use the full absolute path to both Python and the main.py script
  2. Replace API credentials with your actual values from Step 1
  3. 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:

ls -la ~/.mcp_telegram_*

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

rm /Users/username/.mcp_telegram_numberininternationalformat*

Try step 3 again.

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

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.

  1. Functions
    1. Setup
      1. Recommended set up
      2. Step 1: Get Your Telegram API Credentials
      3. Step 2: Set Up Python Environment
      4. Step 3: Add IDs
      5. Step 4: Run authentication
      6. Step 5: Add to Claude Desktop
      7. VERY IMPORTANT:
      8. Step 6 (optional):
    2. That's It!
      1. Customisation
        1. Pesky troubleshooting

          Related MCP Servers

          • -
            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
            16
            JavaScript
          • A
            security
            A
            license
            A
            quality
            An MCP server that allows Claude to create, manage and publish X/Twitter posts directly through the chat interface.
            Last updated -
            5
            35
            Python
            MIT License
            • Apple
          • -
            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 -
            85
            Python
            Apache 2.0
            • Apple
            • Linux
          • -
            security
            F
            license
            -
            quality
            An MCP server that allows Claude to interact with Discord by providing tools for sending/reading messages and managing server resources through Discord's API.
            Last updated -
            JavaScript

          View all related MCP servers

          ID: iw2s0g45fo