快速-MCP-电报

Name: 快速-MCP-电报
Author: leshchenko1979

作者：leshchenko197910 星标更新：2025-11-20

安装使用来源：spider==github.com

项目介绍

Fast MCP Telegram Server - 面向生产的Telegram集成，适用于具有全面搜索、消息传递和直接API访问能力的人工智能助手。

🌐 演示

打开 https://tg-mcp.redevest.ru/setup 开始身份验证流程。
完成后，您将收到一个带有您的Bearer令牌的mcp.json。
使用配置与您的MCP客户端检查此MCP服务器的功能。
或者立即尝试HTTP-MTProto桥接，使用curl（替换TOKEN）：

curl -X POST "https://tg-mcp.redevest.ru/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"params": {"peer": "me", "message": "Hello from Demo!"}}'

✨ 功能

功能	描述
🔐 多用户认证	生产就绪的Bearer令牌认证，会话隔离和LRU缓存管理
🌐 HTTP-MTProto 桥接	通过curl直接访问任何Telegram API方法，实体解析和安全护栏
🔍 智能搜索	全局及聊天内消息搜索，支持多查询和智能去重
🏗️ 双传输	支持无缝开发（标准I/O）和生产（HTTP）部署
📁 安全文件处理	富媒体分享，SSRF防护，大小限制和相册支持
💬 高级消息传递	发送、编辑、回复带格式的消息，文件附件和电话号码消息
📊 统一会话管理	单一配置系统用于设置和服务器，支持多账户
👥 智能联系人发现	搜索用户、群组、频道，统一实体模式和丰富资料
⚡ 高性能	异步操作，并行查询，连接池和内存优化
🛡️ 生产可靠性	自动重连，结构化日志，全面错误处理
🎯 AI优化	字面参数约束，适合LLM的API设计，以及MCP工具注解
🌍 Web设置界面	基于浏览器的身份验证流程，即时生成配置

🛠️ 可用工具

工具	目的	主要特性
`search_messages_globally`	在所有聊天中搜索	多词查询，日期过滤，聊天类型过滤
`search_messages_in_chat`	在特定聊天中搜索	支持“me”用于保存的消息，可选查询最新消息
`send_message`	发送新消息	文件附件（URL/本地），格式化（markdown/html），回复
`edit_message`	编辑现有消息	文本格式化，保留消息结构
`read_messages`	根据ID读取特定消息	批量读取，完整消息内容及元数据
`find_chats`	查找用户/群组/频道	多词搜索，联系人发现，用户名/电话查找
`get_chat_info`	获取详细资料信息	成员数量，简介/关于，在线状态，丰富数据
`send_message_to_phone`	发送电话号码消息	自动联系人管理，可选清理，文件支持
`invoke_mtproto`	直接访问Telegram API	原始MTProto方法，实体解析，安全护栏

📖 有关详细工具文档和示例，请参阅工具参考

🚀 快速开始

1. 从PyPI安装

pip install fast-mcp-telegram

2. 与Telegram进行身份验证

fast-mcp-telegram-setup --api-id="your_api_id" --api-hash="your_api_hash" --phone-number="+123456789"

🌐 更喜欢浏览器？ 运行服务器并打开 /setup 进行身份验证并下载一个即用型 mcp.json。您也可以通过同一界面重新授权现有会话。

3. 配置您的MCP客户端

STDIO模式（开发时使用Cursor IDE）：

{
  "mcpServers": {
    "telegram": {
      "command": "fast-mcp-telegram",
      "env": {
        "API_ID": "your_api_id",
        "API_HASH": "your_api_hash",
        "PHONE_NUMBER": "+123456789"
      }
    }
  }
}

HTTP_AUTH模式（生产时使用Bearer令牌）：

{
  "mcpServers": {
    "telegram": {
      "url": "https://your-server.com",
      "headers": {
        "Authorization": "Bearer AbCdEfGh123456789KLmnOpQr..."
      }
    }
  }
}

4. 开始使用！

{"tool": "search_messages_globally", "params": {"query": "hello", "limit": 5}}
{"tool": "send_message", "params": {"chat_id": "me", "message": "Hello from AI!"}}

📝 有关详细的安装说明，请参阅安装指南

🏗️ 服务器模式

模式	传输	认证	使用场景
STDIO	标准I/O	禁用	使用Cursor IDE开发
HTTP_NO_AUTH	HTTP	禁用	开发HTTP服务器
HTTP_AUTH	HTTP	必需（Bearer令牌）	生产部署

🌐 HTTP-MTProto 桥接

通过HTTP请求直接访问任何Telegram API方法 - 执行任何Telegram MTProto方法，自动实体解析和安全护栏。

快速示例

# 使用自动实体解析发送消息
curl -X POST "https://your-domain.com/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "params": {"peer": "@username", "message": "Hello from curl!"},
        "resolve": true
      }'

# 使用params_json发送消息（适用于n8n和其他工具）
curl -X POST "https://your-domain.com/mtproto-api/messages.SendMessage" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "params_json": "{\"peer\": \"@username\", \"message\": \"Hello from curl!\"}",
        "resolve": true
      }'

# 使用peer解析获取消息历史
curl -X POST "https://your-domain.com/mtproto-api/messages.getHistory" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "params": {"peer": "me", "limit": 10},
        "resolve": true
      }'

📖 有关完整的MTProto桥接文档，请参阅 MTProto桥接指南

📚 文档

安装指南 - 详细的安装和配置
部署指南 - Docker部署和生产设置
工具参考 - 完整工具文档和示例
搜索指南 - 搜索最佳实践和限制
操作指南 - 健康监控和故障排除
项目结构 - 代码组织和架构
贡献指南 - 开发设置和贡献指南

🔒 安全性

关键安全特性：

带有会话隔离的Bearer令牌认证
文件下载的SSRF防护
危险方法阻断，可选择覆盖
会话文件安全性和自动清理

📖 有关完整的安全信息，请参阅 SECURITY.md

🤝 贡献

我们欢迎贡献！请参阅我们的贡献指南：

开发设置说明
测试指南
代码质量标准
拉取请求过程

贡献者的快速入门：

分叉仓库
阅读贡献指南
创建一个功能分支
进行更改并添加测试
提交拉取请求

📄 许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

FastMCP - MCP服务器框架
Telethon - Telegram API库
Model Context Protocol - 协议规范

为AI自动化社区制作 ❤️

⭐ 在GitHub上点赞我们 • 💬 加入我们的社区

</div>

mcp-name: io.github.leshchenko1979/fast-mcp-telegram