Telegram MCP 服务器
关于
该服务器是 Telegram API 和 AI 助手之间的桥梁，基于模型上下文协议。
重要提示：使用此服务器前，请确保您已阅读并理解Telegram API 服务条款。任何滥用 Telegram API 的行为都可能导致您的帐户被暂停。
Related MCP server: Telegram MCP Server
什么是 MCP？
模型上下文协议 (MCP) 是一个允许 AI 应用（例如 Claude Desktop）连接到外部工具和数据源的系统。它为 AI 助手提供了一种清晰、安全的方式，使其能够使用本地服务和 API，同时保持用户的控制权。
这个服务器是做什么的？
到目前为止，服务器只提供对 Telegram API 的只读访问权限。
[x] 获取对话列表（聊天、频道、群组）
[x] 获取给定对话框中的（未读）消息列表
[ ] 将频道标记为已读
[ ] 按日期和时间检索消息
[ ] 下载媒体文件
[ ] 获取联系人列表
[ ] 起草消息
...
实际用例
[x] 创建未读消息的摘要
[ ] 查找生日即将到来的联系人并安排问候
[ ] 查找关于给定主题的讨论，总结它们并提供链接列表
先决条件
安装
如果您已经安装了服务器，则可以使用uv tool upgrade --reinstall命令进行更新。
如果要删除服务器，请使用uv tool uninstall mcp-telegram命令。
配置
Telegram API 配置
在使用服务器之前，您需要连接到 Telegram API。
从Telegram API获取 API ID 和哈希值
运行以下命令：
mcp-telegram sign-in --api-id <your-api-id> --api-hash <your-api-hash> --phone-number <your-phone-number>输入您从 Telegram 收到的代码以连接到 API。
如果您启用了双因素身份验证，则可能需要密码。
要从 Telegram API 注销，请使用mcp-telegram logout命令。
Claude桌面配置
配置 Claude Desktop 以识别 Exa MCP 服务器。
打开Claude桌面配置文件：
在 MacOS 中，配置文件位于
~/Library/Application Support/Claude/claude_desktop_config.json在 Windows 中，配置文件位于
%APPDATA%\Claude\claude_desktop_config.json
**注意：**您还可以在 Claude Desktop 应用程序的设置中找到 claude_desktop_config.json
添加服务器配置
{ "mcpServers": { "mcp-telegram": { "command": "mcp-server", "env": { "TELEGRAM_API_ID": "<your-api-id>", "TELEGRAM_API_HASH": "<your-api-hash>", }, } } } }
电报配置
在使用 Telegram 的 API 之前，您需要获取自己的 API ID 和哈希值：
使用要使用的开发者帐户的电话号码登录您的 Telegram 帐户。
单击 API 开发工具。
将出现“创建新应用程序”窗口。填写您的应用程序详细信息。无需输入任何 URL，目前只有前两个字段（应用程序标题和简称）可以稍后更改。
最后点击“创建应用程序”。请记住，您的 API 哈希值是保密的，Telegram 不会允许您撤销它。请勿将其发布到任何地方！
发展
入门
克隆存储库
安装依赖项
uv sync运行服务器
uv run mcp-telegram --help
可以将工具添加到src/mcp_telegram/tools.py文件中。
如何添加新工具：
创建一个继承自 ToolArgs 的新类
class NewTool(ToolArgs): """Description of the new tool.""" pass该类的属性将用作该工具的参数。类的文档字符串将用作工具的描述。
为新类实现 tool_runner 函数
@tool_runner.register async def new_tool(args: NewTool) -> t.Sequence[TextContent | ImageContent | EmbeddedResource]: pass该函数应返回 TextContent、ImageContent 或 EmbeddedResource 的序列。该函数应为异步函数，并接受新类的单个参数。
完成！重启客户端，新工具就可以使用了。
验证可以通过 Claude Desktop 或直接运行工具来完成。
在终端中调试服务器
要直接运行该工具，请使用以下命令：
在检查器中调试服务器
MCP 检查器是一款使用精美 UI 帮助调试服务器的工具。要运行它，请使用以下命令：
不要忘记在检查器中定义环境变量 TELEGRAM_API_ID 和 TELEGRAM_API_HASH。
故障排除
消息“无法连接到 MCP 服务器 mcp-telegram”
如果您在 Claude Desktop 中看到消息“无法连接到 MCP 服务器 mcp-telegram”，则表示服务器配置不正确。
请尝试以下操作：
在配置文件中使用
uv二进制文件的完整路径检查配置文件中克隆存储库的路径