Telegram MCP server

• Telegram MCP server

  • About

  • What is MCP?

  • What does this server do?

  • Practical use cases

  • Prerequisites

  • Installation

  • Configuration

    • Telegram API Configuration

    • Claude Desktop Configuration

    • Telegram Configuration

  • Development

    • Getting started

    • Debugging the server in terminal

    • Debugging the server in the Inspector

  • Troubleshooting

    • Message 'Could not connect to MCP server mcp-telegram'

About

The server is a bridge between the Telegram API and the AI assistants and is based on the Model Context Protocol.

Related MCP server: tdlib-mcp-server

What is MCP?

The Model Context Protocol (MCP) is a system that lets AI apps, like Claude Desktop, connect to external tools and data sources. It gives a clear and safe way for AI assistants to work with local services and APIs while keeping the user in control.

What does this server do?

Tools available in this project:

• ListDialogs — list chats / channels / groups

• ListMessages — list messages with id, date, sender, text (search / unread filters)

• GetMessage — read a single message by id

• SendMessage — send a text message

• EditMessage — edit your message

• DeleteMessages — delete messages

• ForwardMessages — forward messages (optional delete originals ≈ move)

• CreateGroup — create a basic group or megagroup

• MarkAsRead — mark a dialog as read

• ListFolders — list chat folders (dialog filters)

• UpsertFolder — create or update a folder with dialog ids

• DeleteFolder — delete a folder by id

• ReorderFolders — set folder order

• MuteDialog — mute notifications (forever or for N seconds)

• UnmuteDialog — unmute notifications

• ArchiveDialog / UnarchiveDialog — move dialogs to/from archive

• LeaveDialog — leave a group/channel or remove a private dialog

• Download media files

• Get the list of contacts

Practical use cases

• Create a summary of the unread messages

• Send replies or drafts from an AI assistant

• Forward / clean up messages across chats

• Create a group and invite users by id

• Organize chats into Telegram folders

• Mute, archive or leave noisy chats

• Find contacts with upcoming birthdays and schedule a greeting

• Find discussions on a given topic, summarize them and provide a list of links

Prerequisites

• uv tool

Installation

uv tool install git+https://github.com/dimajolkin/mcp-telegram

Original read-only project: sparfenyuk/mcp-telegram.

Configuration

Telegram API Configuration

Before you can use the server, you need to connect to the Telegram API.

1. Get the API ID and hash from Telegram API

2. Run the following command:

   mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>

   Enter the code you received from Telegram to connect to the API.

   The password may be required if you have two-factor authentication enabled.

Claude Desktop Configuration

Configure Claude Desktop to recognize the Exa MCP server.

1. Open the Claude Desktop configuration file:

   • in MacOS, the configuration file is located at ~/Library/Application Support/Claude/claude_desktop_config.json

   • in Windows, the configuration file is located at %APPDATA%\Claude\claude_desktop_config.json

   Note: You can also find claude_desktop_config.json inside the settings of Claude Desktop app

2. Add the server configuration

   {
     "mcpServers": {
       "mcp-telegram": {
         "command": "mcp-telegram",
         "env": {
           "TELEGRAM_API_ID": "<your-api-id>",
           "TELEGRAM_API_HASH": "<your-api-hash>"
         }
       }
     }
   }

Telegram Configuration

Before working with Telegram’s API, you need to get your own API ID and hash:

1. Login to your Telegram account with the phone number of the developer account to use.

2. Click under API Development tools.

3. A 'Create new application' window will appear. Fill in your application details. There is no need to enter any URL, and only the first two fields (App title and Short name) can currently be changed later.

4. Click on 'Create application' at the end. Remember that your API hash is secret and Telegram won’t let you revoke it. Don’t post it anywhere!

Development

Getting started

1. Clone the repository

2. Install the dependencies

   uv sync

3. Run the server

   uv run mcp-telegram --help

Tools can be added to the src/mcp_telegram/tools.py file.

How to add a new tool:

1. Create a new class that inherits from ToolArgs

   class NewTool(ToolArgs):
       """Description of the new tool."""
       pass

   Attributes of the class will be used as arguments for the tool. The class docstring will be used as the tool description.

2. Implement the tool_runner function for the new class

   @tool_runner.register
   async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]:
       pass

   The function should return a sequence of TextContent, ImageContent or EmbeddedResource. The function should be async and accept a single argument of the new class.

3. Done! Restart the client and the new tool should be available.

Validation can accomplished either through Claude Desktop or by running the tool directly.

Debugging the server in terminal

To run the tool directly, use the following command:

# List all available tools
uv run cli.py list-tools

# Run the concrete tool
uv run cli.py call-tool --name ListDialogs --arguments '{"unread": true}'

Debugging the server in the Inspector

The MCP inspector is a tool that helps to debug the server using fancy UI. To run it, use the following command:

npx @modelcontextprotocol/inspector uv run mcp-telegram

Troubleshooting

Message 'Could not connect to MCP server mcp-telegram'

If you see the message 'Could not connect to MCP server mcp-telegram' in Claude Desktop, it means that the server configuration is incorrect.

Try the following:

• Use the full path to the uv binary in the configuration file

• Check the path to the cloned repository in the configuration file