Telegram Interface for Model Context Protocol (MCP)

• Telegram MCP Agent
• Overview
• Understanding MCP
• Agent Functionality
• Application Scenarios
• Prerequisites for Setup
• Installation Procedure
• Configuration Details
  • Telegram Credential Setup
  • AI Client Environment Configuration (e.g., Claude Desktop)
  • Platform-Specific Settings
• Development & Contribution
  • Initiating Development
  • Debugging in Console
  • Debugging via Inspector UI
• Troubleshooting Common Issues
  • Connection Failure: 'mcp-telegram' server unavailable

Overview

This service acts as a secure intermediary, translating requests between the AI's operating environment and the official Telegram Application Programming Interface, adhering strictly to the Model Context Protocol standards.

[!IMPORTANT] Users must thoroughly review and comply with the Telegram API Terms of Service. Non-adherence risks account termination by Telegram.

Understanding MCP

The Model Context Protocol (MCP) establishes a standardized, secure communication layer enabling intelligent agents, such as Claude Desktop, to interface with external data repositories and service APIs, ensuring user oversight over all external data access.

Agent Functionality

Currently, this service grants read-only access to the underlying Telegram data structures.

• [x] Enumerating accessible dialogs (conversations, channels, groups)
• [x] Fetching messages (including unread status) from specified dialogs
• [ ] Mechanism for marking conversations as read
• [ ] Ability to query messages based on precise temporal stamps
• [ ] Functionality to retrieve attached media assets
• [ ] Listing user contacts
• [ ] Managing message drafts
• ...

Application Scenarios

• [x] Generation of concise digests from accumulated unread correspondence
• [ ] Proactive identification of contacts with impending birthdays for automated salutations
• [ ] Topic-based information retrieval across discussions, with resultant synthesis and link curation

Prerequisites for Setup

• The uv dependency manager tool

Installation Procedure

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

[!NOTE] For updating an existing installation, execute uv tool upgrade --reinstall.

[!NOTE] To completely remove the service, use the command uv tool uninstall mcp-telegram.

Configuration Details

Telegram Credential Setup

Prior to operation, authorization with the Telegram API endpoints is mandatory.

1. Obtain your unique API Identifier and Secret Hash from the Telegram API development portal
2. Execute the sign-in command, substituting placeholders with your credentials:

bash mcp-telegram sign-in --api-id --api-hash --phone-number

You will be prompted to input the verification code sent to your Telegram account.

If Two-Factor Authentication is active, a password prompt will follow.

[!NOTE] To revoke API access for this service, employ the mcp-telegram logout command.

AI Client Environment Configuration (e.g., Claude Desktop)

Configure the AI application to recognize this newly deployed MCP service endpoint.

1. Locate and open the client's configuration manifest:
2. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Windows: %APPDATA%\Claude\claude_desktop_config.json

Note: The configuration file path is often accessible within the application's settings panel.

1. Integrate the server definition block:

   { "mcpServers": { "mcp-telegram": { "command": "mcp-server", "env": { "TELEGRAM_API_ID": "", "TELEGRAM_API_HASH": "", }, } } } }

Platform-Specific Settings

Detailed instructions for obtaining the necessary API keys from Telegram:

1. Authenticate on the platform using the designated developer phone number.
2. Navigate to the API Development tools section.
3. Initiate the 'Create new application' workflow, populating the required fields. Note that only the 'App title' and 'Short name' are modifiable post-creation.
4. Finalize by clicking 'Create application'. Crucially, treat the generated API hash as highly sensitive information; do not expose it publicly.

Development & Contribution

Initiating Development

1. Clone the source code repository.
2. Install required project dependencies:

bash uv sync

1. Launch the service runner (to see available commands):

bash uv run mcp-telegram --help

New integrations should be implemented within the src/mcp_telegram/tools.py module.

Procedure for adding a novel tool:

1. Define a new class inheriting from ToolArgs:

python class NewTool(ToolArgs): """Documentation string describing the tool's capability.""" pass

Class attributes define the tool's input parameters. The class docstring serves as the public description.

1. Implement the asynchronous execution handler for the new class definition:

python @tool_runner.register async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]: # Implementation logic goes here pass

This function must be asynchronous and accept only the structured argument object derived from NewTool. It should yield a sequence of TextContent, ImageContent, or EmbeddedResource objects as its output.

1. Completion! Upon restarting the client connection, the new tool becomes accessible.

Tool validation can be verified either through the AI client's interface or by executing the tool directly via the local debugging CLI.

Debugging in Console

To exercise tool functionality directly from the command line:

bash

View all registered tool signatures

uv run cli.py list-tools

Invoke a specific tool with parameters

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

Debugging via Inspector UI

The MCP Inspector provides a graphical interface for server debugging. Invoke it using:

bash npx @modelcontextprotocol/inspector uv run mcp-telegram

[!WARNING] Ensure that the TELEGRAM_API_ID and TELEGRAM_API_HASH environment variables are explicitly set within the Inspector session environment.

Troubleshooting Common Issues

Connection Failure: 'mcp-telegram' server unavailable

This error typically indicates a configuration mismatch preventing the AI client from locating or initiating the service.

Recommendations for resolution:

• Specify the absolute, fully qualified path to the uv executable within the client configuration file.
• Verify that the configuration points to the correct directory structure of the cloned repository.