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