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

Name: 任务处理结果： tg_mcp tg_mcp
Author: leshchenko1979

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

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

项目介绍

Fast MCP Telegram Server - 面向生产的人工智能助手集成，具备全面搜索、消息传递和直接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 工具注解
🌍 网络设置界面	基于浏览器的认证流程，即时生成配置

🛠️ 可用工具

工具	目的	主要特性
`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

🤝 贡献

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

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

贡献者的快速入门：

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

📄 许可证

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

🙏 致谢

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

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

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

</div>

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