AI导哈

Telegram代理MCP

一个简化的Telegram机器人，集成了MCP（模型上下文协议）工具，用于本地开发和调试，支持与外部MCP服务器连接。

  • by BoomBidiBuyBuy
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 BoomBidiBuyBuy/telegram-agent-mcp

使用说明

电报代理MCP

一个简化的Telegram机器人，带有MCP（模型上下文协议），用于本地开发和调试。

此存储库实现了一个代理服务器，允许访问与MCP工具集成的LLM代理。

特性

  • 🤖 LLM代理集成：由OpenAI GPT模型提供支持
  • 🛠️ MCP工具：用于计算、日期/时间等的自定义工具
  • 📱 电报机器人：易于使用的界面
  • 🔧 地方发展：调试和测试的简单设置
  • 🚀 远程MCP服务器：连接到外部MCP服务器
  • 🧠 对话记忆：带有InMemorySaver的内置内存系统

发展

先决条件

  • Python 3.12+
  • uv 包管理器
  • OpenAI API密钥
  • Telegram Bot令牌
  • 外部MCP服务器

环境设置

  1. 创建 .env 文件基于 env.example:
cp env.example .env
  1. 填写所需的环境变量：
# Telegram Bot Configuration
TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here

# OpenAI Configuration
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-5-nano

# MCP Server Configuration
MCP_SERVER_URL=mcp_server_url
MCP_SERVER_TRANSPORT=streamable_http

# Path to JSON with multiple MCP servers
MCP_SERVERS_FILE_PATH=mcp-servers.json

[！重要] 对于开发，您可以使用 mysql 为了 STORAGE_DB 因为它将所有数据保存在内存中。

MCP服务器JSON（带env扩展）

您可以在JSON文件中定义多个MCP服务器。加载器支持环境变量扩展，如 ${VAR} 或 $VAR 在任何字符串字段中。

示例 mcp-servers.json:

{
  "mcpServers": {
    "RemoteHTTP": {
      "transport": "streamable_http",
      "url": "${MCP_SERVER_URL}"
    },
    "LocalSSE": {
      "transport": "sse",
      "url": "http://localhost:${MCP_PORT}/sse"
    }
  }
}

加载服务器时，代理将合并和扩展变量，然后通过连接 langchain_mcp_adapters.

安装

安装依赖项：

uv sync --dev

运行Bot

用一个命令启动机器人：

uv run --env-file .env src/main.py

代理将自动连接到您的MCP服务器 .env 或 mcp-servers.json.

用法

  1. 在Telegram中查找您的机器人
  2. 发送 /start 命令
  3. 发送任何消息，机器人将使用LLM和可用工具进行处理

项目结构

  • src/agent.py -连接到外部MCP服务器的LangChain代理
  • src/main.py -带有消息处理程序的Telegram机器人
  • src/storage.py -数据库存储层
  • src/user.py -用户管理
  • src/envs.py -环境配置

配置

OpenAI设置

  • 模型: gpt-5-nano （默认）或任何其他OpenAI模型
  • 温度: 1 （可配置用于创意）
  • 流媒体: False （为了提高可靠性）

MCP服务器连接

  • 统一资源定位符: MCP_SERVER_URL 或通过 mcp-servers.json
  • 运输：可通过配置 MCP_SERVER_TRANSPORT 或JSON格式
  • 服务器文件: MCP_SERVERS_FILE_PATH （默认值： mcp-servers.json)
  • 自动重新连接：是的，有错误处理功能

内存管理

  • 内存保护程序：用于对话历史的内置LangGraph存储系统
  • 基于线程的隔离：每个用户都有单独的对话上下文
  • 自动持久化：消息之间会自动维护对话历史记录

通信模式

我们支持两种与Telegram服务器通信的方式：

  • 轮询，即当机器人不时地访问电报服务器并检查新消息或事件时
  • 网络钩子，即当bot注册自己的url时，电报服务器应该在那里发送新的消息和事件

这 COMMUNICATION_MODE env变量处理它 轮询 是默认值。

Webhook 配置

首先设置 COMMUNICATION_MODE 向 webhook.

使用webhook需要设置SSL。

此命令生成 private.key 和 cert.pem SSL文件。

openssl req -newkey rsa:2048 -sha256 -nodes -keyout private.key -x509 -days 3650 -out cert.pem

（请求FQDN时使用域名/IP地址）

然后我们需要定义 SSL_KEY_PATH 和 SSL_CERT_PATH env in .env 生成的文件。

这 WEBHOOK_PORT 应设置为80、88、443或8443。

这 WEBHOOK_URL 需要有格式 https://<your-domain-or-ip>:<webhook-port>在这种情况下，URL中需要.Port。

远程MCP服务器设置

要连接到远程MCP服务器：

  1. 确保服务器可访问:

    • 服务器应绑定到 0.0.0.0:8080 （不是 127.0.0.1:8080)
    • 防火墙中的端口8080应打开
    • 服务器应支持 streamable_http 运输

  2. 在中配置 .env:

MCP_SERVER_URL=http://your-server-ip:8080/mcp/
MCP_SERVER_TRANSPORT=streamable_http
  1. 测试连接性:
curl http://your-server-ip:8080/mcp/

调试

测试

uv run pytest -vs

棉毛

运行过梁：

uv run ruff check

格式代码：

uv run ruff format

检查MCP服务器状态

测试MCP服务器是否正在运行：

curl $MCP_SERVER_URL

测试

运行测试：

uv run pytest

运作原理

  1. 外部MCP服务器：FastMCP服务器使用自定义工具在外部运行
  2. 朗链代理：连接到外部MCP服务器并处理用户消息
  3. 电报机器人：处理用户交互并将消息转发给代理
  4. LLM集成：OpenAI GPT处理消息并决定使用哪些工具
  5. 存储器系统：InMemorySaver维护每个用户的对话历史记录

部署

Heroku

Heroku仅与webhook模式集成。

您只需在Heroku网站上设置以下envs：

  • COMMUNICATION_MODE=webhook
  • WEBHOOK_URL=https://<your-app-id>.herokuapp.com/ （请注意，端口不应出现在url中，因为Heroku通过代理与应用程序通信）
  • TELEGRAM_BOT_TOKEN

无需设置 WEBHOOK_PORT, SSL_KEY_PATH 和 SSL_CERT_PATH 因为Heroku在其代理端管理SSL。至于港口，他们通过 PORT 我们使用的env变量，而不是 WEBHOOK_PORT 与他们的方法相结合。

依赖项

关键依赖关系：

  • langchain>=0.2.0
  • langchain-openai>=0.2.0
  • langchain-mcp-adapters>=0.1.0
  • langgraph>=0.6.4
  • fastmcp>=0.1.0
  • python-telegram-bot>=22.3

回复服务MCP（独立）

一个轻量级的独立MCP服务器，允许外部系统从您的Telegram机器人向特定用户触发消息。

环境

添加到您的 .env （或使用默认值）：

REPLY_SERVICE_MCP_HOST=0.0.0.0
REPLY_SERVICE_MCP_PORT=8091

需要 TELEGRAM_BOT_TOKEN 待设定。

跑

uv run --env-file .env python mcp_servers/reply_service/main.py

MCP端点将在以下位置可用：

http://${REPLY_SERVICE_MCP_HOST}:${REPLY_SERVICE_MCP_PORT}/mcp/

从代理使用（可选）

assets/mcp-servers.json 已包含回复服务条目：

{
  "mcpServers": {
    "SimpleMCPServer": {
      "transport": "${MCP_SERVER_TRANSPORT}",
      "url": "${MCP_SERVER_URL}"
    },
    "ReplyService": {
      "transport": "streamable_http",
      "url": "http://${REPLY_SERVICE_MCP_HOST}:${REPLY_SERVICE_MCP_PORT}/mcp/"
    }
  }
}

当代理启动时，它将加载此服务器并将其工具暴露给LLM。

相关 MCP