gmail_category_summary

Summarize unread emails in a specific Gmail category to quickly identify important messages and manage your inbox efficiently.

Instructions

Get a summary of unread emails in one specific category. Returns email count and list of emails matching that category.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`category`	Yes	Category to summarize. Must be one of: navy, kids, financial, action_required.

Implementation Reference

src/mcp_gmail/gmail_client.py:611-636 (handler)

Core handler implementing the tool logic: fetches unread emails matching the specified category using search query built from category matchers, computes counts, and constructs CategorySummary object.

async def get_category_summary(self, category_key: str) -> Optional[CategorySummary]:
    """Get summary for a specific category."""
    if category_key not in self.categories.categories:
        return None

    category = self.categories.categories[category_key]
    max_results = self.categories.summary_settings.get("max_per_category", 10)

    # Search for emails in this category
    search = SearchQuery(
        category=category_key,
        is_unread=True,
        max_results=50,
    )

    emails = await self.list_emails(search)

    return CategorySummary(
        category_key=category_key,
        category_name=category.name,
        priority=category.priority,
        total_count=len(emails),
        unread_count=sum(1 for e in emails if not e.is_read),
        emails=emails[:max_results],
    )

src/mcp_gmail/server_old.py:121-135 (registration)

Registers the gmail_category_summary tool with the MCP server, including name, description, and input schema defining the required 'category' parameter.

Tool(
    name="gmail_category_summary",
    description="Get a summary of unread emails in a specific category",
    inputSchema={
        "type": "object",
        "properties": {
            "category": {
                "type": "string",
                "description": "Category to summarize",
                "enum": ["navy", "kids", "financial", "action_required"],
            },
        },
        "required": ["category"],
    },
),

src/mcp_gmail/server_old.py:345-357 (handler)

Tool dispatch handler in MCP call_tool: validates input, calls GmailClient.get_category_summary, handles errors, formats output as TextContent.

elif name == "gmail_category_summary":
    category = arguments.get("category")
    if not category:
        return [TextContent(type="text", text="Error: category is required")]
    summary = await client.get_category_summary(category)
    if summary is None:
        return [TextContent(type="text", text=f"Unknown category: {category}")]
    return [
        TextContent(
            type="text",
            text=_format_category_summary(summary),
        )
    ]

src/mcp_gmail/server_old.py:810-826 (helper)

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

def _format_category_summary(summary) -> str:
    """Format category summary for display."""
    lines = [
        f"# {summary.category_name}",
        f"**Total:** {summary.total_count} | **Unread:** {summary.unread_count}",
        "",
    ]

    for email in summary.emails:
        status = "📬" if not email.is_read else "📭"
        lines.append(f"{status} **{email.subject}**")
        lines.append(f"   From: {email.sender.email} | {email.date.strftime('%Y-%m-%d %H:%M')}")
        lines.append(f"   {email.snippet[:100]}...")
        lines.append(f"   ID: `{email.id}`")
        lines.append("")

    return "\n".join(lines)

Gmail MCP Server