Gmail MCP Server

Instructions

Implementation Reference

• src/mcp_gmail/server.py:539-620 (handler)

  Main handler implementation for the gmail_get_priorities tool. Builds a complex Gmail search query using matchers from the 'known_priorities' category in config (senders, subjects, labels), applies date filter, excludes routine notifications, optionally unread only, searches, and formats results with previews.

  elif name == "gmail_get_priorities":
      days_back = arguments.get("days_back", 7)
      include_read = arguments.get("include_read", False)
      
      # Get the known_priorities category from config
      categories_config = get_categories_config()
      priority_cat = categories_config.categories.get("known_priorities")
      
      if not priority_cat:
          return [TextContent(
              type="text",
              text="Error: 'known_priorities' category not found in categories.yaml"
          )]
      
      # Build query from category matchers
      query_parts = []
      
      # Add sender patterns
      for sender in priority_cat.matcher.senders:
          query_parts.append(f"from:{sender}")
      
      # Add subject patterns  
      for subject in priority_cat.matcher.subjects:
          # Wrap multi-word subjects in quotes
          if " " in subject:
              query_parts.append(f'subject:"{subject}"')
          else:
              query_parts.append(f"subject:{subject}")
      
      # Add label patterns
      for label in priority_cat.matcher.labels:
          if label.lower() == "starred":
              query_parts.append("is:starred")
          elif label.lower() == "important":
              query_parts.append("is:important")
          else:
              query_parts.append(f"label:{label}")
      
      if not query_parts:
          return [TextContent(
              type="text",
              text="Error: 'known_priorities' category has no matchers defined"
          )]
      
      # Add date filter
      from datetime import datetime, timedelta
      date_after = (datetime.now() - timedelta(days=days_back)).strftime("%Y/%m/%d")
      
      # Combine queries with OR
      combined_query = f"({' OR '.join(query_parts)}) after:{date_after}"
      
      # Exclude routine/junk
      combined_query += " -subject:(autopay) -subject:(scheduled payment) -subject:(payment received) -subject:(statement ready) -category:promotions"
      
      if not include_read:
          combined_query += " is:unread"
      
      # Search for priority emails
      emails = await client.search_emails(combined_query, max_results=50)
      
      if not emails:
          return [TextContent(
              type="text", 
              text=f"No priority emails found in the last {days_back} days."
          )]
      
      # Format results
      lines = [f"📌 **Priority Emails** (last {days_back} days)\n"]
      lines.append(f"Found {len(emails)} priority item(s):\n")
      
      for email in emails:
          status = "📩" if not email.is_read else "📧"
          starred = "⭐ " if email.is_starred else ""
          lines.append(f"{status} {starred}**{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[:100]}...")
          lines.append("")
      
      return [TextContent(type="text", text="\n".join(lines))]

• src/mcp_gmail/server.py:153-169 (registration)

  Tool registration and schema definition for gmail_get_priorities, included in GMAIL_TOOLS list returned by list_tools() handler.

      name="gmail_get_priorities",
      description="Get priority emails based on the 'known_priorities' category in categories.yaml. Searches for emails matching configured senders (Navy, schools, family) and subjects (orders, deployments, scouts, financial alerts). Automatically excludes routine items like autopay confirmations.",
      inputSchema={
          "type": "object",
          "properties": {
              "days_back": {
                  "type": "integer",
                  "description": "How many days back to search for priority emails. Default is 7 days."
              },
              "include_read": {
                  "type": "boolean",
                  "description": "Whether to include already-read emails. Default is false (unread only)."
              }
          },
          "required": []
      },
  ),