Telegram MCP Server

🚀 Telegram MCP Server Guide

Telegram MCP Server serves as a bridge connecting the Telegram API and AI assistants (such as Claude Desktop). By providing a series of tools, this server enables AI assistants to interact with Telegram's messages and features.

⚠️ Important Note

• When using the Telegram API, strictly adhere to its terms and conditions.
• Ensure the security of your API keys and other sensitive information to prevent leakage.

MCP Protocol

MCP (Model Context Protocol) is a protocol for communication between AI applications and external tools and services. Through MCP, AI assistants can:

• Operate Telegram accounts
• Send and receive messages
• Manage conversations
• Utilize Telegram's advanced features

✨ Features

Implemented Features

• List conversations (supports filtering by unread messages)
• Send and receive messages
• Create new conversations
• Retrieve chat history
• Operate Telegram files and media

Features to be Implemented

• Group management
• Channel management
• Scheduled tasks
• API logging

📚 Documentation

Real - world Application Scenarios

1. Create Unread Message Summaries
   Use the MCP server to collect unread messages from Telegram and generate summaries in Claude Desktop.

2. Auto - reply Bot
   Configure server tools to implement an automatic message response function.

3. Batch Processing of Chat History
   Use the MCP server to export and manage a large amount of chat data.

Prerequisites

• Install and configure the uv tool.
• Obtain a Telegram developer account.
• Create a new Telegram application (to get the API ID and HASH).

📦 Installation

Installation Steps

1. Clone the repository using the following command:

   uv clone git+https://github.com/sparfenyuk/mcp-telegram.git
   

2. Run the server in the terminal:

   cd mcp-telegram
   uv run mcp-telegram
   

3. Get help information with the following command:

   uv run mcp-telegram --help
   

Update Steps

uv sync

Uninstallation Steps

uv uninstall mcp-telegram

Configuration Guide

Telegram API Configuration

1. Log in to your Telegram account and enter the developer tools interface.
2. Create a new application and obtain the API ID and API HASH.

Claude Desktop Configuration

Edit the configuration file (usually located at ~/.config/claude/tools.yaml) and add the following content:

full/path/to/uv: &uvcli
  cli: uv
  args:
    - run
    - mcp-telegram

Ensure that the path is correct.

Development Guide

Getting Started

1. Clone the repository:

   uv clone git+https://github.com/sparfenyuk/mcp-telegram.git
   

2. Install dependencies:

   uv sync
   

3. Run the server and view help information:

   uv run mcp-telegram --help
   

Adding New Tools

1. Create a new class in src/mcp_telegram/tools.py:

   class NewTool(Tool):
       """Describe the function of the new tool"""
       async def _run(self, args: List[str], stdin: Optional[bytes]) -> Tuple[int, bytes]:
           # Implement specific functions
   

2. Register the tool using the following decorator:

   @toolkit_register
   class NewTool(Tool):
       pass
   

Debugging Methods

Terminal Debugging

Run the following command to view log information:

uv run mcp-telegram --log=all

Inspector Tool

Start the debugging tool with the following command:

uv inspect mcp-telegram

Troubleshooting

Connection Issues

1. Check if the path of the uv binary file is correct.
2. Ensure that the server is running successfully.

Log Information

View the logs for more information:

uv run mcp-telegram --log=all

With the above guide, you can easily configure and use the Telegram MCP Server. For further assistance, please refer to the official documentation or contact the developer community.