IMAP MCP Server

Instructions

Implementation Reference

• src/imap_mcp/imap_client.py:137-149 (handler)

  The `select_mailbox` method in `ImapClient` handles the actual IMAP `select_folder` logic and returns `MailboxStatus`.

  def select_mailbox(self, mailbox: str) -> MailboxStatus:
      """Select/open a mailbox folder."""
      self._ensure_connected()
      result = self.client.select_folder(mailbox)
      self.current_mailbox = mailbox
      return MailboxStatus(
          name=mailbox,
          exists=result.get(b"EXISTS", 0),
          recent=result.get(b"RECENT", 0),
          unseen=result.get(b"UNSEEN", 0) if b"UNSEEN" in result else 0,
          uidnext=result.get(b"UIDNEXT", 0),
          uidvalidity=result.get(b"UIDVALIDITY", 0),
      )

• src/imap_mcp/server.py:77-84 (registration)

  The tool `select_mailbox` is registered with the MCP server with a description and input schema.

  make_tool(
      "select_mailbox",
      "Select/open a mailbox folder",
      {
          "mailbox": {"type": "string", "description": "Mailbox name (e.g., INBOX, Sent)"},
      },
      ["mailbox"],
  ),

• src/imap_mcp/server.py:494-495 (handler)

  The `handle_tool_call` function in `server.py` routes the `select_mailbox` tool call to the corresponding `imap_client.select_mailbox` implementation.

  elif name == "select_mailbox":
      return imap_client.select_mailbox(args["mailbox"])