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": [] }, ),