IMAP MCP Server

Instructions

Implementation Reference

• src/imap_mcp/imap_client.py:932-1012 (handler)

  The actual implementation of the auto-archive logic in the IMAP client.

  def process_auto_archive(self, dry_run: bool = False) -> dict:
      """Process INBOX and archive emails from listed senders.
  
      Args:
          dry_run: If True, only report what would be archived without moving.
  
      Returns:
          dict with 'archived_count', 'archived_emails', and 'errors'.
      """
      self._ensure_connected()
  
      if not self.auto_archive_senders:
          return {"archived_count": 0, "archived_emails": [], "errors": [], "dry_run": dry_run, "message": "No senders in auto-archive list"}
  
      # Build set of sender emails/domains for fast lookup
      sender_patterns = set()
      for s in self.auto_archive_senders:
          sender_patterns.add(s.email.lower())
  
      # Get archive folder from config
      folders = self.config.get("folders", {})
      archive_folder = folders.get("archive", "Archive")
      inbox_folder = folders.get("inbox", "INBOX")
  
      # Select INBOX
      self.client.select_folder(inbox_folder)
  
      # Search all emails
      uids = self.client.search(["ALL"])
      if not uids:
          return {"archived_count": 0, "archived_emails": [], "errors": [], "dry_run": dry_run, "message": "INBOX is empty"}
  
      # Fetch envelopes to check senders
      messages = self.client.fetch(uids, ["ENVELOPE"])
  
      to_archive = []
      archived_emails = []
      errors = []
  
      for uid, data in messages.items():
          envelope = data.get(b"ENVELOPE")
          if not envelope or not envelope.from_:
              continue
  
          # Get sender email
          f = envelope.from_[0]
          mailbox = f.mailbox.decode() if f.mailbox else ""
          host = f.host.decode() if f.host else ""
          sender_email = f"{mailbox}@{host}".lower()
          sender_domain = f"@{host}".lower()
  
          # Check if sender matches
          if sender_email in sender_patterns or sender_domain in sender_patterns:
              subject = ""
              if envelope.subject:
                  try:
                      subject = envelope.subject.decode("utf-8", errors="replace")
                  except Exception:
                      subject = str(envelope.subject)
  
              to_archive.append(uid)
              archived_emails.append({
                  "uid": uid,
                  "sender": sender_email,
                  "subject": subject[:100],
              })
  
      # Move emails if not dry run
      if to_archive and not dry_run:
          try:
              self.client.move(to_archive, archive_folder)
          except Exception as e:
              errors.append(f"Failed to move emails: {str(e)}")
  
      return {
          "archived_count": len(to_archive),
          "archived_emails": archived_emails,
          "errors": errors,
          "dry_run": dry_run,
          "message": f"{'Would archive' if dry_run else 'Archived'} {len(to_archive)} emails",
      }

• src/imap_mcp/server.py:680-683 (registration)

  The registration of the 'process_auto_archive' tool in the MCP server's call handler.

  elif name == "process_auto_archive":
      return imap_client.process_auto_archive(
          dry_run=args.get("dry_run", False),
      )