Mail MCP Server

Instructions

Implementation Reference

• src/mail_mcp/operations/fetch.py:88-117 (handler)

  The core handler logic that fetches email data from an IMAP server.

  def get_email(
      self, folder: str, uid: int, headers_only: bool = False, decode_bodies: bool = True
  ) -> dict[str, Any]:
      """
      Fetch a single email.
  
      Args:
          folder: Folder containing the email
          uid: Email sequence number or UID
          headers_only: If True, fetch only headers (default: False)
          decode_bodies: If True, decode quoted-printable/base64 (default: True)
  
      Returns:
          Dictionary containing:
          - uid: Email UID
          - sequence_number: Sequence number
          - headers: Email headers as dict
          - subject: Subject line
          - from: From address
          - to: To addresses
          - date: Date header
          - message_id: Message-ID
          - body: Body text (if not headers_only)
          - html: HTML body (if available)
          - attachments: List of attachments (if any)
  
      Raises:
          EmailFetchError: If fetch fails
  
      Example:

• src/mail_mcp/tools/__init__.py:93-121 (schema)

  Tool definition and schema for the 'get_email' tool, used by the MCP server to expose the functionality.

  Tool(
      name="get_email",
      description="Get detailed email information",
      inputSchema={
          "type": "object",
          "properties": {
              "folder": {
                  "type": "string",
                  "description": "Folder containing the email (default: INBOX)",
                  "default": "INBOX",
              },
              "message_id": {
                  "type": "string",
                  "description": "Message ID (sequence number)",
              },
              "uid": {
                  "type": "string",
                  "description": "Unique ID of the message",
              },
              "include_body": {
                  "type": "boolean",
                  "description": "Include email body (default: true)",
                  "default": True,
              },
          },
          "anyOf": [
              {"required": ["message_id"]},
              {"required": ["uid"]},
          ],