📌Overview

Purpose: To serve as a bridge between the Telegram API and AI assistants, facilitating the safe and effective interaction with Telegram's features through the Model Context Protocol (MCP).

Overview: The Telegram MCP server allows AI applications, such as Claude Desktop, to access and interact with Telegram's functionalities in a structured manner. It provides read-only access to essential Telegram resources, ensuring transparency and user control over the data accessed.

Key Features:

Read-Only Access: Offers capabilities to read dialogs, retrieve unread messages, and obtain contacts, all while maintaining user data protection.
Integration with AI Tools: Seamlessly connects with AI applications, enabling advanced functionalities like summarizing unread messages and organizing communications.

Telegram MCP server

About

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

Important:
Ensure that you have read and understood the Telegram API Terms of Service before using this server.
Any misuse of the Telegram API may result in the suspension of your account.

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 provides 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?

Currently, the server provides read-only access to the Telegram API:

Get the list of dialogs (chats, channels, groups)
Get the list of (unread) messages in a given dialog
Mark channel as read
Retrieve messages by date and time
Download media files
Get the list of contacts
Draft a message

Practical use cases

Create a summary of unread messages
Find contacts with upcoming birthdays and schedule greetings
Find discussions on a topic, summarize them, and provide a list of links

Prerequisites

uv tool

Installation

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

Note:
To update the server, use uv tool upgrade --reinstall.
To uninstall the server, use uv tool uninstall mcp-telegram.

Configuration

Telegram API Configuration

To connect the server to the Telegram API:

Get your API ID and hash from Telegram API
Run the sign-in command:
```
mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>
```
Enter the code sent by Telegram.
If two-factor authentication is enabled, a password may be required.

To log out from the Telegram API, run:
mcp-telegram logout

Claude Desktop Configuration

Configure Claude Desktop to recognize the MCP server:

Open the Claude Desktop configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
You can also find this file in the settings of the Claude Desktop app.

Add the server configuration:

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

Telegram Configuration

To get your API ID and hash for Telegram:

Log in to your Telegram developer account using the phone number you want to use.
Go to API Development Tools.
Create a new application: fill in the app title and short name (other fields are optional).
After creation, keep your API hash secure. Telegram does not allow revoking it. Do not share it publicly.

Development

Getting Started

Clone the repository.
Install dependencies:
```
uv sync
```
Run the server:
```
uv run mcp-telegram --help
```

Adding Tools

Tools are defined in src/mcp_telegram/tools.py.

Steps to add a new tool:

Create a new class inheriting from ToolArgs:
```
class NewTool(ToolArgs):
    """Description of the new tool."""
    pass
```
The docstring is used as the tool description.

Implement the corresponding tool_runner function:

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

Restart the client for the tool to be available.

You can validate tools via Claude Desktop or by running them directly.

Debugging the server in terminal

List tools:

uv run cli.py list-tools

Run a specific tool (example):

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

Debugging the server in the Inspector

Run the MCP inspector:

npx @modelcontextprotocol/inspector uv run mcp-telegram

Warning: Define environment variables TELEGRAM_API_ID and TELEGRAM_API_HASH in the inspector.

Troubleshooting

Message: "Could not connect to MCP server mcp-telegram"

If this appears in Claude Desktop, the server configuration may be incorrect.

Try:

Using the full path to the uv binary in the configuration.
Checking the path to the cloned repository in the configuration.