Skip to main content
Glama
enesjakozh
sparfenyuk

Telegram MCP Server

by sparfenyuk
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

Telegram MCP server

About

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

IMPORTANT

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

Related MCP server: telegram-briefing-mcp

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?

As of not, 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 the given dialog

  • Mark chanel 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 the unread messages

  • Find contacts with upcoming birthdays and schedule a greeting

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

Prerequisites

Installation

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

If you have already installed the server, you can update it usinguv tool upgrade --reinstall command.

NOTE

If you want to delete the server, use theuv tool uninstall mcp-telegram command.

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.

NOTE

To log out from the Telegram API, use themcp-telegram logout command.

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-server",
        "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
WARNING

Do not forget to define Environment Variables TELEGRAM_API_ID and TELEGRAM_API_HASH in the inspector.

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

Available Tools

2 tools
ListDialogsC

List available dialogs, chats and channels.

ParametersJSON Schema
NameRequiredDescriptionDefault
unreadNo
archivedNo
ignore_pinnedNo

TDQS

C2.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states what the tool does (listing) without mentioning permissions, rate limits, pagination, or response format. For a list tool with zero annotation coverage, this leaves critical behavioral traits unspecified, making it inadequate for safe and effective use.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is appropriately sized and front-loaded, making it easy to parse quickly. However, it lacks depth, which affects completeness but not conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a list operation with 3 parameters), no annotations, no output schema, and low schema coverage, the description is incomplete. It doesn't explain what 'available' means, how results are returned, or parameter usage, leaving significant gaps for the agent to operate effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description repeats the tool name and provides no information about parameters. With 3 parameters (unread, archived, ignore_pinned) and 0% schema description coverage, the schema only provides titles and types without explanations. The description fails to compensate by adding any meaning or context for these parameters, leaving them undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool's purpose as listing available dialogs, chats, and channels, which is clear but vague. It uses the verb 'list' with the resources 'dialogs, chats and channels', but doesn't specify scope (e.g., all or filtered) or distinguish it from the sibling tool ListMessages. This makes it adequate but with gaps in specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling tool ListMessages, prerequisites, or exclusions. Without any usage context, the agent must infer when this tool is appropriate, which is insufficient for effective tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

ListMessagesA
List messages in a given dialog, chat or channel. The messages are listed in order from newest to oldest.

If `unread` is set to `True`, only unread messages will be listed. Once a message is read, it will not be
listed again.

If `limit` is set, only the last `limit` messages will be listed. If `unread` is set, the limit will be
the minimum between the unread messages and the limit.
ParametersJSON Schema
NameRequiredDescriptionDefault
dialog_idYes
unreadNo
limitNo

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the ordering (newest to oldest), the effect of 'unread' (filters to unread only and excludes read messages), and how 'limit' interacts with 'unread' (minimum between them). However, it misses details like pagination, error handling, or authentication needs, leaving gaps for a mutation-like operation (listing can imply read access).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded, starting with the core purpose. Each sentence adds value: the first states the action, the second explains ordering, and the subsequent ones detail parameter effects without redundancy. There's zero waste, making it efficient for an AI agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and 3 parameters with 0% schema coverage, the description provides a decent foundation by explaining purpose and parameter interactions. However, it lacks information on return values (e.g., message format), error cases, or authentication requirements, making it incomplete for full contextual understanding in a read operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds significant meaning beyond the schema by explaining the semantics of 'unread' (filters to unread messages and excludes read ones) and 'limit' (applies to last messages, with interaction rules when combined with 'unread'). This covers key aspects of the 3 parameters, though it doesn't detail 'dialog_id' beyond context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('List') and resource ('messages in a given dialog, chat or channel'), making the purpose immediately understandable. It distinguishes from the sibling tool 'ListDialogs' by specifying messages rather than dialogs. However, it doesn't explicitly contrast with potential alternatives beyond the sibling tool, keeping it from a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by explaining the effects of the 'unread' and 'limit' parameters, which suggests when to use them. However, it lacks explicit guidance on when to choose this tool over alternatives (e.g., vs. a search tool or the sibling 'ListDialogs'), and doesn't mention prerequisites like required permissions or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

C2.9/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: ListDialogs retrieves available dialogs/chats/channels, while ListMessages retrieves messages within a specific dialog/chat/channel. There is no overlap or ambiguity between them.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with PascalCase naming (ListDialogs, ListMessages). The naming is predictable and readable throughout the set.

Tool Count2/5

With only 2 tools, this server feels severely under-scoped for a Telegram integration. While the tools are well-defined, there are obvious gaps in functionality (e.g., sending messages, managing channels, handling media) that limit its usefulness.

Completeness2/5

The tool surface is significantly incomplete for a Telegram server. It only provides read-only listing capabilities for dialogs and messages, missing essential operations like sending messages, creating/editing channels, handling files, or any write/update actions that would be expected in a messaging platform integration.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • telegram-briefing-mcp

    zainbacchus
    A
    license
    Not graded
    quality
    C
    maintenance
    A read-only Telegram MCP server that retrieves messages from your DMs, groups, and channels, enabling Claude to generate executive briefings from Telegram conversations.
    MIT

  • telegram-mcp

    Sultonbek006
    A
    license
    Not graded
    quality
    D
    maintenance
    A Telegram integration for Claude, Cursor, and other MCP-compatible clients, exposing account, chat, message, contact, media, folder, and admin operations through the Model Context Protocol using Telethon.
    Apache 2.0

  • Telegram MCP Server

    Asadullayev06
    A
    license
    Not graded
    quality
    B
    maintenance
    A Telegram integration for Claude, Cursor, and other MCP-compatible clients. It exposes Telegram account, chat, message, contact, media, folder, and admin operations through the Model Context Protocol using Telethon.
    Apache 2.0

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sparfenyuk/mcp-telegram'

If you have feedback or need assistance with the MCP directory API, please join our Discord server