gmail_list_labels

Retrieve all Gmail labels, including system and user-created ones, to organize and manage email categories effectively.

Instructions

List all Gmail labels including both system labels (INBOX, SENT, etc.) and user-created labels. Returns label names and IDs.

Input Schema

TableJSON Schema

Name	Required	Description	Default
No arguments

Implementation Reference

src/mcp_gmail/server.py:187-194 (schema)

Tool schema definition for 'gmail_list_labels' with no input parameters.

Tool(
    name="gmail_list_labels",
    description="List all Gmail labels including both system labels (INBOX, SENT, etc.) and user-created labels. Returns label names and IDs.",
    inputSchema={
        "type": "object",
        "properties": {},
        "required": []
    },

src/mcp_gmail/server.py:1128-1131 (registration)
Registration of all Gmail tools including 'gmail_list_labels' via the MCP server's list_tools handler.
```
@server.list_tools()
async def list_tools() -> list[Tool]:
    return GMAIL_TOOLS
```
src/mcp_gmail/server.py:708-711 (handler)
Tool handler in handle_call_tool that executes gmail_list_labels by calling GmailClient.get_labels() and formatting the result.
```
elif name == "gmail_list_labels":
    labels = await client.get_labels()
    return [TextContent(type="text", text=_format_labels_detailed(labels))]
```

src/mcp_gmail/gmail_client.py:380-388 (handler)

Core handler implementation in GmailClient that calls the Gmail API to list all labels.

async def get_labels(self) -> list[dict]:
    """Get all Gmail labels."""
    try:
        results = self.service.users().labels().list(userId="me").execute()
        return results.get("labels", [])
    except HttpError as e:
        logger.error(f"Failed to get labels: {e}")
        raise

src/mcp_gmail/server.py:1331-1365 (helper)

Helper function to format the list of labels into a detailed text response, separating system and user labels.

def _format_labels_detailed(labels: list[dict]) -> str:
    """Format labels list with full details for display.
    
    Args:
        labels: List of label dictionaries.
        
    Returns:
        str: Formatted string representation.
    """
    lines = ["Gmail Labels:\n"]
    
    system_labels = []
    user_labels = []
    
    for label in labels:
        if label.get("type") == "system":
            system_labels.append(label)
        else:
            user_labels.append(label)
    
    if system_labels:
        lines.append("System Labels:")
        for label in sorted(system_labels, key=lambda x: x.get("name", "")):
            lines.append(f"  - {label['name']} (ID: {label['id']})")
    
    if user_labels:
        lines.append("\nUser Labels:")
        for label in sorted(user_labels, key=lambda x: x.get("name", "")):
            color_info = ""
            if label.get("color"):
                color_info = f" [color: {label['color'].get('backgroundColor', 'default')}]"
            lines.append(f"  - {label['name']} (ID: {label['id']}){color_info}")
    
    return "\n".join(lines)

Gmail MCP Server