IMAP MCP Server

Instructions

Implementation Reference

• src/imap_mcp/imap_client.py:489-513 (handler)

  The actual implementation of the search_emails functionality in the IMAP client class.

  def search_emails(
      self, query: str, mailbox: Optional[str] = None, limit: int = 50
  ) -> list[EmailHeader]:
      """Search emails with query (IMAP SEARCH syntax or text)."""
      self._ensure_connected()
      if mailbox:
          self.select_mailbox(mailbox)
      elif not self.current_mailbox:
          self.select_mailbox("INBOX")
  
      # Try to parse as IMAP search criteria, fallback to TEXT search
      try:
          if any(kw in query.upper() for kw in ["FROM", "TO", "SUBJECT", "BODY", "ALL", "UNSEEN"]):
              uids = self.client.search(query.split())
          else:
              uids = self.client.search(["TEXT", query])
      except Exception:
          uids = self.client.search(["TEXT", query])
  
      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:174-183 (registration)

  Registration of the search_emails tool within the MCP server definition.

  make_tool(
      "search_emails",
      "Search emails with query",
      {
          "query": {"type": "string", "description": "Search query (IMAP SEARCH syntax or text)"},
          "mailbox": {"type": "string", "description": "Mailbox name (default: current)"},
          "limit": {"type": "number", "description": "Max results (default: 50)"},
      },
      ["query"],
  ),