任务处理结果： tg_mcp <中文翻译> tg_mcp

<img alt="英雄图片" src="https://github.com/user-attachments/assets/635236f6-b776-41c7-b6e5-0dd14638ecc1" />

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

🌐 演示

1. 打开 https://tg-mcp.redevest.ru/setup 开始认证流程。
2. 完成后，您将收到一个带有 Bearer 令牌的 mcp.json 文件。
3. 使用您的 MCP 客户端中的配置来检查此 MCP 服务器的功能。
4. 或者立即尝试 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!"}}'

📖 目录

• ✨ 功能
• 🚀 快速开始
• 🏗️ 服务器模式
• 🌐 HTTP-MTProto 桥接
• 📚 文档
• 🔒 安全
• 🤝 贡献
• 📄 许可证

✨ 功能

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

🛠️ 可用工具

工具	目的	主要特性
search_messages_globally	跨所有聊天搜索	多项查询、日期过滤、聊天类型过滤
search_messages_in_chat	在特定聊天中搜索	支持“我”以查找已保存的消息，可选查询最新消息
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

🤝 贡献

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

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

贡献者的快速入门：

1. 分叉仓库
2. 阅读 贡献指南
3. 创建功能分支
4. 进行更改并添加测试
5. 提交拉取请求

📄 许可证

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

🙏 致谢

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

---

<div align="center">

为人工智能自动化社区制作 ❤️

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

</div>

---

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