电报MCP服务器
- 关于 - 什么是MCP？ - 这个服务器做什么？ - 实际使用案例 - 先决条件 - 安装 - 配置 - 电报API配置 - Claude桌面配置 - 电报配置 - 发展 - 入门 - 在终端中调试服务器 - 在检查器中调试服务器 - 故障排除 - 消息“无法连接到MCP服务器MCP电报”
关于
该服务器是Telegram API和人工智能助手之间的桥梁，基于 模型上下文协议.
\[！重要\] 确保您已阅读并理解 电报API服务条款 在使用此服务器之前。 任何对Telegram API的滥用都可能导致您的帐户被暂停。
什么是MCP？
模型上下文协议（MCP）是一个允许人工智能应用程序（如Claude Desktop）连接到外部工具和数据源的系统。它为AI助手提供了一种清晰安全的方式来使用本地服务和API，同时让用户保持控制。
这个服务器做什么？
截至目前，服务器提供对Telegram API的只读访问。
- \[x\] 获取对话列表（聊天、频道、组）
- \[x\] 获取给定对话框中的（未读）邮件列表
- \[\]马克·夏奈尔已读
- \[\]按日期和时间检索邮件
- \[\]下载媒体文件
- \[\]获取联系人列表
- \[\]起草一条消息
- ...
实际使用案例
- \[x\] 创建未读邮件的摘要
- \[\]查找即将到来的生日联系人并安排问候
- \[\]查找关于给定主题的讨论，对其进行总结并提供链接列表
先决条件
安装
uv tool install git+https://github.com/sparfenyuk/mcp-telegram\[！注意\] 如果您已经安装了服务器，可以使用以下命令进行更新 uv tool upgrade --reinstall 命令。\[！注意\] 如果要删除服务器，请使用 uv tool uninstall mcp-telegram 命令。配置
电报API配置
在使用服务器之前，您需要连接到Telegram API。
- 从获取API ID和哈希 电报API
- 运行以下命令：
mcp-telegram sign-in --api-id --api-hash --phone-number 输入您从Telegram收到的代码以连接到API。
如果启用了双因素身份验证，则可能需要密码。
\[！注意\] 要从Telegram API注销，请使用 mcp-telegram logout 命令。Claude桌面配置
配置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
- 添加服务器配置
{
"mcpServers": {
"mcp-telegram": {
"command": "mcp-server",
"env": {
"TELEGRAM_API_ID": "",
"TELEGRAM_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类的属性将用作工具的参数。 类docstring将用作工具描述。
- 为新类实现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}'在检查器中调试服务器
MCP检查器是一个使用花哨的UI帮助调试服务器的工具。要运行它，请使用以下命令：
npx @modelcontextprotocol/inspector uv run mcp-telegram\[！警告\] 不要忘记在检查器中定义环境变量TELEGRAM_API_ID和TELEGRAM-API_HASH。
故障排除
消息“无法连接到MCP服务器MCP电报”
如果您在Claude Desktop中看到消息“无法连接到MCP服务器MCP电报”，则表示服务器配置不正确。
尝试以下操作：
- 使用完整路径
uv配置文件中的二进制文件 - 检查配置文件中克隆存储库的路径