金大哥 - fast-mcp-telegram MCP 详情

article

README

🚀 快速MCP Telegram服务器

快速MCP Telegram服务器 是一个为AI助手提供的、可用于生产环境的Telegram集成方案，具备全面的搜索、消息发送和直接API访问功能。

](https://python.org) ](https://opensource.org/licenses/MIT) ](https://github.com/leshchenko1979/fast-mcp-telegram)

🌐 演示

打开 https://tg-mcp.redevest.ru/setup 开始认证流程。
完成后，你将获得一个包含Bearer令牌的可用 mcp.json 文件。
将此配置用于你的MCP客户端，以体验此MCP服务器的功能。
或者，立即使用curl尝试HTTP‑MTProto桥接（替换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方法，具备实体解析和安全防护机制 | | 🔍 智能搜索 | 支持全局和按聊天消息搜索，具备多查询支持和智能去重功能 | | 🏗️ 双传输模式 | 无缝支持开发（标准输入输出）和生产（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客户端

标准输入输出模式（使用Cursor IDE进行开发）：

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

HTTP认证模式（使用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!"}}

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

🏗️ 服务器模式

| 模式 | 传输方式 | 认证方式 | 使用场景 | |------|----------|----------------|----------| | 标准输入输出 | 标准输入输出 | 禁用 | 使用Cursor IDE进行开发 | | HTTP无认证 | HTTP | 禁用 | 开发用HTTP服务器 | | HTTP认证 | HTTP | 必需（Bearer令牌） | 生产环境部署 |

🌐 HTTP-MTProto桥接

可通过curl直接访问任何Telegram API方法 - 通过HTTP请求执行任何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
      }'

# 获取消息历史记录并解析对等实体
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库
模型上下文协议 - 协议规范

为AI自动化社区用心打造

⭐ 在GitHub上给我们加星 • 💬 加入我们的社区

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

fast-mcp-telegram