IMAP MCP Server

Instructions

Implementation Reference

• src/imap_mcp/imap_client.py:461-480 (handler)

  The actual implementation of the get_thread tool logic in the IMAP client.

  def get_thread(self, uid: int, mailbox: Optional[str] = None) -> list[EmailHeader]:
      """Get email thread/conversation."""
      self._ensure_connected()
      if mailbox:
          self.select_mailbox(mailbox)
  
      # Get the email to find its references
      email_data = self.get_email(uid, mailbox)
      message_id = email_data.header.message_id
      subject = email_data.header.subject
  
      # Search for related emails by subject (simplified thread detection)
      if subject:
          # Remove Re: Fwd: etc. prefixes
          clean_subject = subject
          for prefix in ["Re:", "RE:", "Fwd:", "FWD:", "Fw:", "AW:", "Aw:"]:
              clean_subject = clean_subject.replace(prefix, "").strip()
  
          uids = self.client.search(["SUBJECT", clean_subject])
          if uids:

• src/imap_mcp/server.py:164-172 (registration)

  Registration of the get_thread tool in the server configuration.

  make_tool(
      "get_thread",
      "Get email thread/conversation",
      {
          "uid": {"type": "number", "description": "Email UID (any email in thread)"},
          "mailbox": {"type": "string", "description": "Mailbox name (default: current)"},
      },
      ["uid"],
  ),

• src/imap_mcp/server.py:542-546 (handler)

  Handling the get_thread tool call by routing it to the imap_client.

  elif name == "get_thread":
      return imap_client.get_thread(
          uid=args["uid"],
          mailbox=args.get("mailbox"),
      )