IMAP MCP Server

Instructions

Implementation Reference

• src/imap_mcp/imap_client.py:868-884 (handler)

  The core implementation of the idle_watch tool, which uses IMAP IDLE to monitor a mailbox for a specified timeout.

  def idle_watch(
      self, mailbox: str = "INBOX", timeout: int = 300
  ) -> dict:
      """Start watching mailbox for new emails (IMAP IDLE) - single mailbox, temporary."""
      self._ensure_connected()
      self.select_mailbox(mailbox)
  
      self.client.idle()
      responses = self.client.idle_check(timeout=timeout)
      self.client.idle_done()
  
      return {
          "mailbox": mailbox,
          "responses": [str(r) for r in responses],
      }
  
  # === Auto-Archive ===

• src/imap_mcp/server.py:397-404 (registration)

  Tool registration definition for idle_watch, including its schema (input parameters).

  make_tool(
      "idle_watch",
      "Start watching mailbox for new emails (IMAP IDLE) - single mailbox, temporary",
      {
          "mailbox": {"type": "string", "description": "Mailbox to watch (default: INBOX)"},
          "timeout": {"type": "number", "description": "Watch timeout in seconds (default: 300)"},
      },
  ),

• src/imap_mcp/server.py:660-664 (handler)

  The server-side dispatch logic that routes the MCP tool call to the imap_client.idle_watch method.

  elif name == "idle_watch":
      return imap_client.idle_watch(
          mailbox=args.get("mailbox", "INBOX"),
          timeout=args.get("timeout", 300),
      )