Telegram MCP Server

Instructions

        发送图片到 Telegram

        ⚠️ 使用场景：
        - 生成了图表、可视化结果
        - 创建了截图、示意图
        - 需要用户查看图片内容
        - 图片格式：PNG, JPG, GIF, WebP 等

        参数：
        - image_path: 图片文件路径（相对于项目目录或绝对路径）
        - caption: 可选说明文字

        示例：
        telegram_send_image(
            image_path="output/chart.png",
            caption="性能测试结果图表"
        )
        

Implementation Reference

• telegram_mcp_server/server.py:961-1023 (handler)

  The handler function that executes the telegram_send_image tool: validates input, resolves image path relative to project, checks file existence, constructs caption, and sends the image to Telegram using the sendPhoto API endpoint.

  async def handle_telegram_send_image(session, arguments: dict) -> list[TextContent]:
      """Handle telegram_send_image tool"""
      image_path = arguments.get("image_path", "")
      caption = arguments.get("caption", "")
  
      if not image_path:
          return [TextContent(type="text", text="错误: image_path 参数不能为空")]
  
      # Resolve image path (relative to project or absolute)
      if not os.path.isabs(image_path):
          full_path = os.path.join(session.project_path, image_path)
      else:
          full_path = image_path
  
      # Check if file exists
      if not os.path.exists(full_path):
          return [TextContent(
              type="text",
              text=f"❌ 图片文件不存在: {image_path}"
          )]
  
      if not os.path.isfile(full_path):
          return [TextContent(
              type="text",
              text=f"❌ 不是文件（可能是目录）: {image_path}"
          )]
  
      # Build caption
      if not caption:
          caption = f"🖼️ [{session.session_id}] {image_path}"
      else:
          caption = f"🖼️ [{session.session_id}] {caption}"
  
      # Update session
      session.update_activity()
  
      # Send image to Telegram using HTTP API
      try:
          import httpx
  
          url = f"https://api.telegram.org/bot{config.TELEGRAM_BOT_TOKEN}/sendPhoto"
  
          with open(full_path, 'rb') as f:
              files = {'photo': (os.path.basename(image_path), f, 'image/jpeg')}
              data = {
                  'chat_id': session.chat_id,
                  'caption': caption
              }
  
              async with httpx.AsyncClient() as client:
                  response = await client.post(url, files=files, data=data, timeout=30.0)
                  response.raise_for_status()
  
          return [TextContent(
              type="text",
              text=f"✅ 已发送图片到 Telegram (会话: {session.session_id}, 图片: {image_path})"
          )]
      except Exception as e:
          return [TextContent(
              type="text",
              text=f"❌ 发送图片失败: {str(e)}"
          )]

• telegram_mcp_server/server.py:410-445 (registration)

  Registration of the telegram_send_image tool in the list_tools() decorator, including name, description, and input schema definition.

  Tool(
      name="telegram_send_image",
      description="""
      发送图片到 Telegram
  
      ⚠️ 使用场景：
      - 生成了图表、可视化结果
      - 创建了截图、示意图
      - 需要用户查看图片内容
      - 图片格式：PNG, JPG, GIF, WebP 等
  
      参数：
      - image_path: 图片文件路径（相对于项目目录或绝对路径）
      - caption: 可选说明文字
  
      示例：
      telegram_send_image(
          image_path="output/chart.png",
          caption="性能测试结果图表"
      )
      """,
      inputSchema={
          "type": "object",
          "properties": {
              "image_path": {
                  "type": "string",
                  "description": "图片文件路径"
              },
              "caption": {
                  "type": "string",
                  "description": "可选说明文字"
              }
          },
          "required": ["image_path"]
      }
  ),

• telegram_mcp_server/server.py:681-682 (registration)

  Dispatch logic in the main @server.call_tool() function that routes calls to the telegram_send_image handler.

  elif name == "telegram_send_image":
      return await handle_telegram_send_image(session, arguments)

• telegram_mcp_server/server.py:431-444 (schema)

  Input schema definition for the telegram_send_image tool, specifying required image_path and optional caption.

  inputSchema={
      "type": "object",
      "properties": {
          "image_path": {
              "type": "string",
              "description": "图片文件路径"
          },
          "caption": {
              "type": "string",
              "description": "可选说明文字"
          }
      },
      "required": ["image_path"]
  }