IMAP MCP Server

Instructions

Implementation Reference

• src/imap_mcp/imap_client.py:515-531 (handler)

  The actual implementation of the tool logic that interacts with the IMAP client.

  def search_by_sender(
      self, sender: str, mailbox: Optional[str] = None, limit: int = 50
  ) -> list[EmailHeader]:
      """Search emails by sender address."""
      self._ensure_connected()
      if mailbox:
          self.select_mailbox(mailbox)
      elif not self.current_mailbox:
          self.select_mailbox("INBOX")
  
      uids = self.client.search(["FROM", sender])
      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:184-193 (registration)

  The MCP tool registration and schema definition for search_by_sender.

  make_tool(
      "search_by_sender",
      "Search emails by sender address",
      {
          "sender": {"type": "string", "description": "Sender email address or name"},
          "mailbox": {"type": "string", "description": "Mailbox name (default: current)"},
          "limit": {"type": "number", "description": "Max results (default: 50)"},
      },
      ["sender"],
  ),

• src/imap_mcp/server.py:555-560 (handler)

  The MCP tool handler in server.py that routes the tool call to the client implementation.

  elif name == "search_by_sender":
      return imap_client.search_by_sender(
          sender=args["sender"],
          mailbox=args.get("mailbox"),
          limit=args.get("limit", 50),
      )