📌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
What is MCP?
What does this server do?
Practical Use Cases
Prerequisites
Installation
Configuration
Development
Troubleshooting

About

The Telegram MCP server is a bridge between the Telegram API and AI assistants, based on the Model Context Protocol (MCP). Ensure that you read and understand the Telegram API Terms of Service before using this server, as misuse may lead to suspension of your account.

What is MCP?

The Model Context Protocol (MCP) allows AI applications to connect with external tools and data sources, maintaining user control while interacting with local services and APIs.

What does this server do?

The server provides read-only access to the Telegram API:

Fetch dialogs (chats, channels, groups)
Retrieve (unread) messages in dialogs

Practical Use Cases

Summarize unread messages
Schedule greetings for contacts with upcoming birthdays
Summarize discussions on specific topics

Prerequisites

uv tool

Installation

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

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

Configuration

Telegram API Configuration

To connect to the Telegram API, obtain the API ID and hash from Telegram API and run:

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

To log out, use the command:

mcp-telegram logout

Claude Desktop Configuration

Open the Claude Desktop configuration file (location varies by OS).
Add server configuration:

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

Telegram Configuration

Login to your Telegram account.
Access API Development tools.
Create a new application and save the API hash securely.

Development

Getting Started

Clone the repository.
Install the dependencies:

uv sync

Run the server:

uv run mcp-telegram --help

To add a new tool, create a class that inherits from ToolArgs and implement the tool_runner function.

Debugging the Server in Terminal

To run the tool directly, use:

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

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

Debugging the Server in the Inspector

Run the MCP inspector using:

npx @modelcontextprotocol/inspector uv run mcp-telegram

Make sure to define the environment variables TELEGRAM_API_ID and TELEGRAM_API_HASH in the inspector.

Troubleshooting

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

This error indicates an incorrect server configuration. Try:

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

mcp-telegram