IMAP MCP Server

Instructions

Implementation Reference

• src/imap_mcp/imap_client.py:429-475 (handler)

  The actual implementation of the download_attachment tool in the IMAP client class.

  def download_attachment(
      self, uid: int, attachment_index: int, mailbox: Optional[str] = None
  ) -> tuple[str, str, bytes]:
      """Download attachment content (returns filename, content_type, base64 data)."""
      import base64
  
      self._ensure_connected()
      if mailbox:
          self.select_mailbox(mailbox)
  
      data = self.client.fetch([uid], ["BODY[]"])
      if uid not in data:
          raise ValueError(f"Email with UID {uid} not found")
  
      raw_body = data[uid].get(b"BODY[]", b"")
      msg = email.message_from_bytes(raw_body)
  
      index = 0
      for part in msg.walk():
          content_disposition = str(part.get("Content-Disposition", ""))
          if "attachment" in content_disposition or "inline" in content_disposition:
              filename = part.get_filename()
              if filename:
                  if index == attachment_index:
                      filename = self._decode_header(filename)
                      content_type = part.get_content_type()
                      payload = part.get_payload(decode=True)
                      return filename, content_type, base64.b64encode(payload)
                  index += 1
  
      raise ValueError(f"Attachment at index {attachment_index} not found")
  
  def get_thread(self, uid: int, mailbox: Optional[str] = None) -> list[EmailHeader]:
      """Get email thread/conversation."""
      self._ensure_connected()
      if mailbox:
          self.select_mailbox(mailbox)
  
      # Get the email to find its references
      email_data = self.get_email(uid, mailbox)
      message_id = email_data.header.message_id
      subject = email_data.header.subject
  
      # Search for related emails by subject (simplified thread detection)
      if subject:
          # Remove Re: Fwd: etc. prefixes
          clean_subject = subject

• src/imap_mcp/server.py:154-163 (registration)

  The definition and registration of the download_attachment tool in the server script.

  make_tool(
      "download_attachment",
      "Download attachment content (base64)",
      {
          "uid": {"type": "number", "description": "Email UID"},
          "attachmentIndex": {"type": "number", "description": "Attachment index (0-based)"},
          "mailbox": {"type": "string", "description": "Mailbox name (default: current)"},
      },
      ["uid", "attachmentIndex"],
  ),

• src/imap_mcp/server.py:531-537 (handler)

  The tool handler logic in server.py that calls the imap_client implementation.

  elif name == "download_attachment":
      filename, content_type, data = imap_client.download_attachment(
          uid=args["uid"],
          attachment_index=args["attachmentIndex"],
          mailbox=args.get("mailbox"),
      )
      return {