Fast MCP Telegram

🚀 快速MCP Telegram服务器

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

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

🌐 演示

1. 打开 https://tg-mcp.redevest.ru/setup 开始认证流程。
2. 完成后，你将获得一个包含Bearer令牌的可用 mcp.json 文件。
3. 将此配置用于你的MCP客户端，以体验此MCP服务器的功能。
4. 或者，立即使用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!"}}'

📖 目录

• ✨ 主要特性
• 🚀 快速开始
• 🏗️ 服务器模式
• 🌐 HTTP-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!"}}

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

🏗️ 服务器模式

🌐 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

🤝 贡献代码

我们欢迎贡献代码！请参阅我们的 贡献指南 了解：

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

贡献者快速入门：

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

📄 许可证

本项目采用MIT许可证 - 有关详细信息，请参阅 LICENSE 文件。

🙏 致谢

• FastMCP - MCP服务器框架
• Telethon - Telegram API库
• 模型上下文协议 - 协议规范

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