项目简介 Fast MCP Telegram Server 是一个基于 Model Context Protocol (MCP) 构建的服务器，旨在为大型语言模型 (LLM) 客户端提供与Telegram平台交互的标准化接口。它允许AI助手通过调用预定义工具来执行各种Telegram操作，例如搜索消息、发送消息、管理联系人以及直接访问Telegram的MTProto API。该服务器支持多种部署模式，包括开发阶段的STDIO和无认证HTTP模式，以及生产环境下的带Bearer Token认证的HTTP模式，确保了安全性和可扩展性。

主要功能点

多用户认证: 生产级Bearer Token认证，支持会话隔离和LRU缓存管理。
HTTP-MTProto 网桥: 允许通过HTTP请求直接访问任何Telegram API方法，支持实体解析和安全防护。
智能搜索: 支持全局和特定聊天内的消息搜索，具备多查询支持和智能去重功能。
文件处理: 安全地分享富媒体文件，包括SSRF保护、大小限制和相册支持。
高级消息功能: 发送、编辑、回复消息，支持文本格式（Markdown/HTML）、文件附件和手机号消息发送。
统一会话管理: 单一配置系统支持多账户设置和服务器运行。
智能联系人发现: 搜索用户、群组和频道，提供统一的实体模式和丰富的档案信息。
AI优化: 友好的API设计，支持MCP ToolAnnotations，以便LLM更好地理解和调用工具。
Web设置界面: 提供基于浏览器的认证流程，可即时生成配置。

安装步骤

安装Python包: 确保你的Python版本是3.10或更高。然后通过pip安装：

pip install fast-mcp-telegram

获取Telegram API凭证: 访问 my.telegram.org/apps 创建一个新应用，获取 'API ID' 和 'API Hash'。如果你想作为机器人运行，还需要从 BotFather 获取 'Bot Token'。
认证Telegram会话: 根据你的使用场景选择认证方式：
- 命令行认证（推荐生产环境）: 运行以下命令进行认证，替换为你的真实凭证和手机号（包含国家代码，如'+12345678900'）。如果作为机器人，请提供'--bot-token'而不是'--phone-number'。
```
fast-mcp-telegram-setup --api-id="你的API_ID" --api-hash="你的API_HASH" --phone-number="+你的手机号"
```
- 浏览器认证（推荐开发环境或首次设置）: 先启动服务器（见下一步），然后在浏览器中访问 '/setup' 路径（例如 'http://localhost:8000/setup' 或 'https://你的域名/setup'），按照指示完成认证流程并下载 'mcp.json' 配置文件。

服务器配置 MCP服务器是给MCP客户端（如Cursor IDE或其他LLM应用）使用的。MCP客户端需要配置服务器的连接信息。以下是三种主要服务器模式的配置示例：

STDIO模式 (开发环境，例如Cursor IDE): 这种模式下，MCP服务器作为子进程运行，并通过标准输入输出与客户端通信，无需额外认证。

{
  "mcpServers": {
    "telegram": {
      "command": "fast-mcp-telegram",
      "env": {
        "API_ID": "你的API_ID",         // 从Telegram应用获取的API ID
        "API_HASH": "你的API_HASH",       // 从Telegram应用获取的API Hash
        "PHONE_NUMBER": "+你的手机号"     // 用于用户认证的手机号 (可选，如果通过Web Setup认证则不需要)
        // "SESSION_NAME": "你的会话名"  // 可选，如果使用自定义会话名 (默认为'telegram')
      }
    }
  }
}

注意: 'API_ID' 和 'API_HASH' 也可以通过环境变量 'API_ID' 和 'API_HASH' 提供给 'fast-mcp-telegram' 命令。'PHONE_NUMBER' 同样。

HTTP_AUTH模式 (生产环境，带Bearer Token认证): 这种模式下，MCP服务器作为HTTP服务运行，并通过Bearer Token进行认证。认证令牌在 'fast-mcp-telegram-setup' 命令行认证后或Web设置界面下载的 'mcp.json' 中提供。

{
  "mcpServers": {
    "telegram": {
      "url": "https://你的服务器域名/mcp", // 你的MCP Telegram服务器的URL
      "headers": {
        "Authorization": "Bearer 你的Bearer令牌" // setup命令或Web设置界面生成的Bearer令牌
      }
    }
  }
}

注意: 请将 'https://你的服务器域名/mcp' 替换为你的实际服务器地址，并将 '你的Bearer令牌' 替换为你在认证步骤中获得的令牌。

HTTP_NO_AUTH模式 (开发环境，无认证HTTP服务): 这种模式下，MCP服务器作为HTTP服务运行，但禁用认证，适用于本地开发和测试。

{
  "mcpServers": {
    "telegram": {
      "url": "http://localhost:8000/mcp" // 本地运行的MCP Telegram服务器URL
    }
  }
}

注意: 此模式不安全，仅用于开发目的。

基本使用方法 配置好MCP客户端后，你的LLM（如Cursor IDE中的AI助手）就可以通过调用Fast MCP Telegram Server提供的工具来与Telegram交互了。

搜索消息:

{"tool": "search_messages_globally", "params": {"query": "你好", "limit": 5}}

发送消息:

{"tool": "send_message", "params": {"chat_id": "me", "message": "来自AI的问候！"}}

查找聊天/联系人:

{"tool": "find_chats", "params": {"query": "我的朋友", "chat_type": "private"}}

直接调用MTProto API:

{"tool": "invoke_mtproto", "params": {"method_full_name": "messages.SendMessage", "params_json": "{\"peer\": \"me\", \"message\": \"Hello from API!\"}"}}

请根据你的MCP客户端的具体调用方式来使用这些工具。

关键词

信息