Telegram MCP Server

Instructions

Implementation Reference

• mcp-server/mcp-server.py:46-64 (handler)

  MCP tool handler for 'send_message': proxies the message sending request to the HTTP API server via POST.

  @mcp.tool(
      name="send_message",
      description="Send a message to an entity with optional markup and reply",
  )
  async def send_message(
      entity_id: int | str,
      content: str = "",
      reply_to_message_id: int = None,
  ) -> dict:
      return post(
          f"{api_endpoint}send_message",
          json={
              "entity": entity_id,
              "content": content,
              "reply_to_message_id": reply_to_message_id,
          },
          headers={"Content-Type": "application/json"},
      ).json()

• http-server/http-api.py:142-146 (schema)

  Pydantic input schema for the /send_message HTTP endpoint, matching the MCP tool parameters.

  class SendMessagePost(BaseModel):
      entity: int | str
      content: str
      reply_message_id: int = None

• http-server/http-api.py:148-163 (helper)

  HTTP endpoint handler that performs the actual Telegram message sending using the Telethon client.

  @app.post("/send_message")
  async def send_message(post_msg: SendMessagePost):
      e_obj = await get_entity(entity=post_msg.entity, raw=True)
  
      message = await client.send_message(
          entity=e_obj,
          message=post_msg.content,
          reply_to=post_msg.reply_message_id,
          parse_mode="html",
      )
  
      if isinstance(message, types.Message) and message.id:
          return {"message_id": message.id}
      else:
          raise HTTPException(status_code=404, detail="Error sending message")