IMAP MCP Server

Instructions

Implementation Reference

• src/imap_mcp/imap_client.py:599-615 (handler)

  Implementation of the search_flagged tool, which selects a mailbox, searches for FLAGGED emails, and returns them as a list of headers.

  def search_flagged(
      self, mailbox: Optional[str] = None, limit: int = 50
  ) -> list[EmailHeader]:
      """Get all flagged/starred emails."""
      self._ensure_connected()
      if mailbox:
          self.select_mailbox(mailbox)
      elif not self.current_mailbox:
          self.select_mailbox("INBOX")
  
      uids = self.client.search(["FLAGGED"])
      uids = sorted(uids, reverse=True)[:limit]
      if not uids:
          return []
  
      messages = self.client.fetch(uids, ["ENVELOPE", "FLAGS", "RFC822.SIZE"])
      return [self._parse_email_header(uid, data) for uid, data in messages.items()]

• src/imap_mcp/server.py:222-229 (registration)

  Tool definition for search_flagged in the MCP server tool list.

  make_tool(
      "search_flagged",
      "Get all flagged/starred emails",
      {
          "mailbox": {"type": "string", "description": "Mailbox name (default: current)"},
          "limit": {"type": "number", "description": "Max results (default: 50)"},
      },
  ),

• src/imap_mcp/server.py:579-583 (handler)

  Handler logic for search_flagged within the server's call_tool function.

  elif name == "search_flagged":
      return imap_client.search_flagged(
          mailbox=args.get("mailbox"),
          limit=args.get("limit", 50),
      )