Gmail MCP Server

Instructions

Implementation Reference

• src/mcp_gmail/server.py:622-704 (handler)

  Handler implementation for 'gmail_get_packages' tool. Constructs a comprehensive Gmail search query for package/shipping notifications from major carriers (Amazon, UPS, FedEx, USPS, DHL) and generic terms. Includes emails from the past N days (default 14), formats results with delivery status icons, and always includes read emails.

  elif name == "gmail_get_packages":
      days_back = arguments.get("days_back", 14)
      
      # Build query for package/shipping emails from common carriers and retailers
      package_queries = [
          # Amazon
          'from:shipment-tracking@amazon.com',
          'from:ship-confirm@amazon.com',
          'from:order-update@amazon.com',
          'subject:"shipped" from:amazon',
          'subject:"out for delivery" from:amazon',
          'subject:"arriving" from:amazon',
          'subject:"delivered" from:amazon',
          # UPS
          'from:ups.com subject:delivery',
          'from:ups.com subject:shipped',
          'from:ups.com subject:tracking',
          # FedEx
          'from:fedex.com subject:delivery',
          'from:fedex.com subject:shipped',
          'from:fedex.com subject:tracking',
          # USPS
          'from:usps.com subject:delivery',
          'from:usps.com subject:shipped',
          'from:usps.com subject:tracking',
          'from:informeddelivery@usps.com',
          # DHL
          'from:dhl.com subject:delivery',
          'from:dhl.com subject:shipment',
          # Generic shipping terms
          'subject:"your order has shipped"',
          'subject:"your package"',
          'subject:"shipment notification"',
          'subject:"tracking number"',
          'subject:"out for delivery"',
          'subject:"expected delivery"',
      ]
      
      # Add date filter
      from datetime import datetime, timedelta
      date_after = (datetime.now() - timedelta(days=days_back)).strftime("%Y/%m/%d")
      
      # Combine queries - always include read emails for package tracking
      combined_query = f"({' OR '.join(package_queries)}) after:{date_after}"
      
      # Search for package emails
      emails = await client.search_emails(combined_query, max_results=50)
      
      if not emails:
          return [TextContent(
              type="text", 
              text=f"No package/shipping emails found in the last {days_back} days."
          )]
      
      # Format results
      lines = [f"📦 **Package Tracking Emails** (last {days_back} days)\n"]
      lines.append(f"Found {len(emails)} shipping/delivery email(s):\n")
      
      for email in emails:
          status = "📩" if not email.is_read else "📧"
          # Try to identify delivery status from subject
          subject_lower = email.subject.lower()
          if "delivered" in subject_lower:
              icon = "✅"
          elif "out for delivery" in subject_lower:
              icon = "🚚"
          elif "arriving" in subject_lower or "expected" in subject_lower:
              icon = "📅"
          elif "shipped" in subject_lower:
              icon = "📤"
          else:
              icon = "📦"
          
          lines.append(f"{status} {icon} **{email.subject}**")
          lines.append(f"   From: {email.sender.name or email.sender.email}")
          lines.append(f"   Date: {email.date.strftime('%Y-%m-%d %H:%M')}")
          lines.append(f"   ID: `{email.id}`")
          if email.snippet:
              lines.append(f"   Preview: {email.snippet[:120]}...")
          lines.append("")
      
      return [TextContent(type="text", text="\n".join(lines))]

• src/mcp_gmail/server.py:171-183 (registration)

  Registration of the 'gmail_get_packages' tool in the GMAIL_TOOLS list, including name, description, and JSON schema for the optional 'days_back' parameter.

      name="gmail_get_packages",
      description="Get package delivery and shipping notification emails. Finds tracking info from Amazon, UPS, FedEx, USPS, and other carriers. Always includes read emails since you want to track all pending deliveries.",
      inputSchema={
          "type": "object",
          "properties": {
              "days_back": {
                  "type": "integer",
                  "description": "How many days back to search for package emails. Default is 14 days."
              }
          },
          "required": []
      },
  ),

• src/mcp_gmail/server.py:173-182 (schema)

  Input schema definition for the 'gmail_get_packages' tool, specifying the optional integer parameter 'days_back'.

  inputSchema={
      "type": "object",
      "properties": {
          "days_back": {
              "type": "integer",
              "description": "How many days back to search for package emails. Default is 14 days."
          }
      },
      "required": []
  },