MCP-Telegram（模型上下文协议电报桥接工具）
一座桥梁，允许 Claude Desktop 通过模型上下文协议访问 Telegram 的聊天和消息，提供只读功能以检索 Telegram 中的对话和消息。
可用工具 （2 个）
该服务在 MCP 协议中暴露的工具，AI 可按需调用
ListDialogs 3 个参数
List available dialogs, chats and channels.
该工具无需必填参数，直接调用即可
ListMessages 3 个参数 需填 1 项
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.
必填参数：dialog_id
服务介绍
Telegram MCP 服务器
关于
该服务器是 Telegram API 和 AI 助手之间的桥梁，基于 Model Context Protocol。
[!IMPORTANT]
在使用此服务器之前，请确保您已阅读并理解 Telegram API 服务条款。
任何对 Telegram API 的滥用都可能导致您的帐户被暂停。
什么是 MCP？
Model Context Protocol (MCP) 是一个系统，允许像 Claude Desktop 这样的 AI 应用程序连接到外部工具和数据源。它为 AI 助手提供了与本地服务和 API 交互的清晰且安全的方式，同时保持用户的控制权。
这个服务器做什么？
目前，该服务器提供对 Telegram API 的只读访问。
- 获取对话列表（聊天、频道、群组）
- 获取给定对话中的（未读）消息列表
- 将频道标记为已读
- 按日期和时间检索消息
- 下载媒体文件
- 获取联系人列表
- 草拟消息
- ...
实际用例
- 创建未读消息摘要
- 查找即将到来生日的联系人并安排问候
- 查找特定主题的讨论，进行总结并提供链接列表
先决条件
安装
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。
-
从 Telegram API 获取 API ID 和 hash
-
运行以下命令：
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 Desktop 配置
配置 Claude Desktop 以识别 Exa MCP 服务器。
-
打开 Claude Desktop 配置文件：
- 在 MacOS 中，配置文件位于
~/Library/Application Support/Claude/claude_desktop_config.json - 在 Windows 中，配置文件位于
%APPDATA%\Claude\claude_desktop_config.json
注意:
您也可以在 Claude Desktop 应用程序的设置中找到 claude_desktop_config.json 文件 - 在 MacOS 中，配置文件位于
-
添加服务器配置
{ "mcpServers": { "mcp-telegram": { "command": "mcp-server", "env": { "TELEGRAM_API_ID": "<your-api-id>", "TELEGRAM_API_HASH": "<your-api-hash>", }, } } } }
Telegram 配置
在使用 Telegram 的 API 之前，您需要获取自己的 API ID 和 hash：
- 使用开发者账户的电话号码登录您的 Telegram 账户。
- 点击进入 API 开发工具。
- 将出现一个“创建新应用”的窗口。填写您的应用详情。目前无需输入任何 URL，且只有前两个字段（应用标题和简称）可以后续更改。
- 最后点击“创建应用”。请记住，您的 API hash 是保密的，Telegram 不允许您撤销它。不要将其发布到任何地方！
开发
入门指南
-
克隆仓库
-
安装依赖项
uv sync -
运行服务器
uv run mcp-telegram --help
工具可以添加到 src/mcp_telegram/tools.py 文件中。
如何添加一个新的工具：
-
创建一个新的类继承自 ToolArgs
class NewTool(ToolArgs): """新工具的描述。""" pass类的属性将作为该工具的参数。
类的文档字符串将作为工具的描述。 -
为新类实现 tool_runner 函数
@tool_runner.register async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]: pass函数应返回 TextContent、ImageContent 或 EmbeddedResource 的序列。
函数应该是异步的，并接受新类的一个参数。 -
完成！重启客户端，新的工具应该可用。
验证可以通过 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}'
在Inspector中调试服务器
MCP Inspector 是一个使用精美用户界面帮助调试服务器的工具。要运行它，请使用以下命令：
npx @modelcontextprotocol/inspector uv run mcp-telegram
[!WARNING]
不要忘记在Inspector中定义环境变量 TELEGRAM_API_ID 和 TELEGRAM_API_HASH。
故障排除
消息 '无法连接到MCP服务器 mcp-telegram'
如果您在Claude Desktop中看到消息“无法连接到MCP服务器 mcp-telegram”，这意味着服务器配置有误。
请尝试以下方法：
- 在配置文件中使用
uv二进制文件的完整路径 - 检查配置文件中克隆仓库的路径
