Skip to main content
Glama
enesjakozh
sparfenyuk

Telegram MCP Server

by sparfenyuk
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Telegram MCP 服务器

关于

该服务器是 Telegram API 和 AI 助手之间的桥梁，基于模型上下文协议。

重要提示：使用此服务器前，请确保您已阅读并理解Telegram API 服务条款。任何滥用 Telegram API 的行为都可能导致您的帐户被暂停。

Related MCP server: telegram-briefing-mcp

什么是 MCP？

模型上下文协议 (MCP) 是一个允许 AI 应用（例如 Claude Desktop）连接到外部工具和数据源的系统。它为 AI 助手提供了一种清晰、安全的方式，使其能够使用本地服务和 API，同时保持用户的控制权。

这个服务器是做什么的？

到目前为止，服务器只提供对 Telegram API 的只读访问权限。

  • [x] 获取对话列表（聊天、频道、群组）

  • [x] 获取给定对话框中的（未读）消息列表

  • [ ] 将频道标记为已读

  • [ ] 按日期和时间检索消息

  • [ ] 下载媒体文件

  • [ ] 获取联系人列表

  • [ ] 起草消息

  • ...

实际用例

  • [x] 创建未读消息的摘要

  • [ ] 查找生日即将到来的联系人并安排问候

  • [ ] 查找关于给定主题的讨论，总结它们并提供链接列表

先决条件

安装

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

[!NOTE] 如果您已经安装了服务器，则可以使用uv tool upgrade --reinstall命令进行更新。

[!NOTE] 如果要删除服务器，请使用uv tool uninstall mcp-telegram命令。

配置

Telegram API 配置

在使用服务器之前，您需要连接到 Telegram API。

  1. 从Telegram API获取 API ID 和哈希值

  2. 运行以下命令：

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

    输入您从 Telegram 收到的代码以连接到 API。

    如果您启用了双因素身份验证，则可能需要密码。

[!NOTE] 要从 Telegram API 注销，请使用mcp-telegram logout命令。

Claude桌面配置

配置 Claude Desktop 以识别 Exa MCP 服务器。

  1. 打开Claude桌面配置文件：

    • 在 MacOS 中，配置文件位于~/Library/Application Support/Claude/claude_desktop_config.json

    • 在 Windows 中，配置文件位于%APPDATA%\Claude\claude_desktop_config.json

    **注意：**您还可以在 Claude Desktop 应用程序的设置中找到 claude_desktop_config.json

  2. 添加服务器配置

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

电报配置

在使用 Telegram 的 API 之前，您需要获取自己的 API ID 和哈希值：

  1. 使用要使用的开发者帐户的电话号码登录您的 Telegram 帐户。

  2. 单击 API 开发工具。

  3. 将出现“创建新应用程序”窗口。填写您的应用程序详细信息。无需输入任何 URL，目前只有前两个字段（应用程序标题和简称）可以稍后更改。

  4. 最后点击“创建应用程序”。请记住，您的 API 哈希值是保密的，Telegram 不会允许您撤销它。请勿将其发布到任何地方！

发展

入门

  1. 克隆存储库

  2. 安装依赖项

    uv sync

  3. 运行服务器

    uv run mcp-telegram --help

可以将工具添加到src/mcp_telegram/tools.py文件中。

如何添加新工具：

  1. 创建一个继承自 ToolArgs 的新类

    class NewTool(ToolArgs):
    """Description of the new tool."""
    pass

    该类的属性将用作该工具的参数。类的文档字符串将用作工具的描述。

  2. 为新类实现 tool_runner 函数

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

    该函数应返回 TextContent、ImageContent 或 EmbeddedResource 的序列。该函数应为异步函数，并接受新类的单个参数。

  3. 完成！重启客户端，新工具就可以使用了。

验证可以通过 Claude Desktop 或直接运行工具来完成。

在终端中调试服务器

要直接运行该工具，请使用以下命令：


# 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}'

在检查器中调试服务器

MCP 检查器是一款使用精美 UI 帮助调试服务器的工具。要运行它，请使用以下命令：

npx @modelcontextprotocol/inspector uv run mcp-telegram

[!WARNING] 不要忘记在检查器中定义环境变量 TELEGRAM_API_ID 和 TELEGRAM_API_HASH。

故障排除

消息“无法连接到 MCP 服务器 mcp-telegram”

如果您在 Claude Desktop 中看到消息“无法连接到 MCP 服务器 mcp-telegram”，则表示服务器配置不正确。

请尝试以下操作：

  • 在配置文件中使用uv二进制文件的完整路径

  • 检查配置文件中克隆存储库的路径

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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updates
    • First observedListDialogs
    • First observedListMessages
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

C2.9/5.0

Scored across 2 tools

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

Related MCP Connectors

Related MCP Servers

  • telegram-briefing-mcp

    zainbacchus
    A
    license
    Not graded
    quality
    D
    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