Gmail MCP Server

Instructions

Implementation Reference

• src/mcp_gmail/gmail_client.py:544-610 (handler)

  Core handler function in GmailClient that fetches recent emails within the specified hours, categorizes them using configured rules, limits per category, sorts by priority, and returns a structured DailySummary.

  async def get_daily_summary(
      self, lookback_hours: Optional[int] = None, include_read: bool = False
  ) -> DailySummary:
      """Generate a daily email summary organized by category."""
      if lookback_hours is None:
          lookback_hours = self.categories.summary_settings.get("daily_lookback_hours", 24)
  
      max_per_category = self.categories.summary_settings.get("max_per_category", 10)
      if include_read is None:
          include_read = self.categories.summary_settings.get("include_read", False)
  
      now = datetime.now(timezone.utc)
      period_start = now - timedelta(hours=lookback_hours)
  
      # Search for recent emails
      search = SearchQuery(
          after_date=period_start,
          is_unread=None if include_read else True,
          max_results=100,
      )
  
      all_emails = await self.list_emails(search)
  
      # Organize by category
      categorized: dict[str, list[EmailSummary]] = {
          cat_key: [] for cat_key in self.categories.categories.keys()
      }
      uncategorized: list[EmailSummary] = []
  
      for email in all_emails:
          if email.categories:
              for cat in email.categories:
                  if cat in categorized:
                      categorized[cat].append(email)
          else:
              uncategorized.append(email)
  
      # Build category summaries
      category_summaries = []
      for cat_key, category in self.categories.categories.items():
          emails = categorized.get(cat_key, [])[:max_per_category]
          if emails:
              category_summaries.append(
                  CategorySummary(
                      category_key=cat_key,
                      category_name=category.name,
                      priority=category.priority,
                      total_count=len(categorized.get(cat_key, [])),
                      unread_count=sum(1 for e in categorized.get(cat_key, []) if not e.is_read),
                      emails=emails,
                  )
              )
  
      # Sort by priority
      priority_order = {"critical": 0, "high": 1, "normal": 2, "low": 3}
      category_summaries.sort(key=lambda c: priority_order.get(c.priority, 2))
  
      return DailySummary(
          generated_at=now,
          period_start=period_start,
          period_end=now,
          total_emails=len(all_emails),
          unread_emails=sum(1 for e in all_emails if not e.is_read),
          categories=category_summaries,
          uncategorized=uncategorized[:max_per_category],
      )

• src/mcp_gmail/server_old.py:102-120 (schema)

  Tool schema definition including input schema with optional 'hours' and 'include_read' parameters for the gmail_daily_summary tool.

      name="gmail_daily_summary",
      description="Generate a daily summary of emails organized by category "
      "(Navy, Kids, Financial, Action Items)",
      inputSchema={
          "type": "object",
          "properties": {
              "hours": {
                  "type": "integer",
                  "description": "How many hours back to look (default: 24)",
                  "default": 24,
              },
              "include_read": {
                  "type": "boolean",
                  "description": "Include already read emails (default: false)",
                  "default": False,
              },
          },
      },
  ),

• src/mcp_gmail/server_old.py:334-343 (registration)

  Tool dispatch/registration in the MCP server's call_tool handler that extracts arguments, calls GmailClient.get_daily_summary, formats the result, and returns TextContent.

  elif name == "gmail_daily_summary":
      hours = arguments.get("hours", 24)
      include_read = arguments.get("include_read", False)
      summary = await client.get_daily_summary(hours, include_read)
      return [
          TextContent(
              type="text",
              text=_format_daily_summary(summary),
          )
      ]

• src/mcp_gmail/server_old.py:780-808 (helper)

  Helper function to format the DailySummary object into a human-readable markdown string for the tool response.

  def _format_daily_summary(summary) -> str:
      """Format daily summary for display."""
      lines = [
          f"# 📧 Daily Email Summary",
          f"**Period:** {summary.period_start.strftime('%Y-%m-%d %H:%M')} to {summary.period_end.strftime('%Y-%m-%d %H:%M')}",
          f"**Total Emails:** {summary.total_emails} ({summary.unread_emails} unread)",
          "",
      ]
  
      for cat in summary.categories:
          priority_icon = {"critical": "🔴", "high": "🟠", "normal": "🟢", "low": "⚪"}.get(
              cat.priority, "🟢"
          )
          lines.append(f"\n## {priority_icon} {cat.category_name} ({cat.unread_count} unread)")
  
          for email in cat.emails[:5]:
              lines.append(f"- **{email.subject}** - {email.sender.email}")
              lines.append(f"  {email.snippet[:80]}...")
  
          if cat.total_count > 5:
              lines.append(f"  _...and {cat.total_count - 5} more_")
  
      if summary.uncategorized:
          lines.append(f"\n## 📋 Other ({len(summary.uncategorized)} emails)")
          for email in summary.uncategorized[:5]:
              lines.append(f"- **{email.subject}** - {email.sender.email}")
  
      return "\n".join(lines)