IMAP MCP Server

Instructions

Implementation Reference

• src/imap_mcp/imap_client.py:324-334 (handler)

  The core implementation of get_email_headers which fetches and parses email headers using the IMAP client.

  def get_email_headers(self, uid: int, mailbox: Optional[str] = None) -> EmailHeader:
      """Get only email headers (faster)."""
      self._ensure_connected()
      if mailbox:
          self.select_mailbox(mailbox)
  
      data = self.client.fetch([uid], ["ENVELOPE", "FLAGS", "RFC822.SIZE"])
      if uid not in data:
          raise ValueError(f"Email with UID {uid} not found")
  
      return self._parse_email_header(uid, data[uid])

• src/imap_mcp/server.py:122-130 (registration)

  Tool definition and registration for 'get_email_headers' within the MCP server.

  make_tool(
      "get_email_headers",
      "Get only email headers (faster)",
      {
          "uid": {"type": "number", "description": "Email UID"},
          "mailbox": {"type": "string", "description": "Mailbox name (default: current)"},
      },
      ["uid"],
  ),

• src/imap_mcp/server.py:515-519 (handler)

  The MCP server call handler that routes the 'get_email_headers' tool request to the IMAP client method.

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