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)