gmail_create_label
Create custom labels in Gmail to organize emails by project, priority, or category. Add optional color coding for visual identification and use nested labels with forward slashes for hierarchical organization.
Instructions
Create a new Gmail label with optional custom colors. Returns the new label's ID.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| label_name | Yes | Name for the new label. Use forward slashes for nested labels (e.g., 'Projects/Work'). | |
| background_color | No | Hex color code for label background (e.g., '#16a765'). Optional. | |
| text_color | No | Hex color code for label text (e.g., '#ffffff'). Optional. |
Implementation Reference
- src/mcp_gmail/server.py:712-737 (handler)MCP tool handler logic for 'gmail_create_label': validates input, checks for existing label, calls GmailClient.create_label, and formats response.elif name == "gmail_create_label": label_name = arguments.get("label_name") if not label_name: return [TextContent(type="text", text="Error: label_name is required.")] # Check if label already exists existing = await client.find_label_by_name(label_name) if existing: return [TextContent( type="text", text=f"Error: A label named '{label_name}' already exists (ID: {existing['id']})." )] background_color = arguments.get("background_color") text_color = arguments.get("text_color") result = await client.create_label(label_name, background_color, text_color) if result["success"]: label = result["label"] return [TextContent( type="text", text=f"Success: Created label '{label['name']}' with ID: {label['id']}" )] else: return [TextContent(type="text", text=f"Error: Failed to create label. {result['error']}")]
- src/mcp_gmail/server.py:196-217 (schema)JSON schema definition for 'gmail_create_label' tool inputs: label_name (required), optional background_color and text_color.Tool( name="gmail_create_label", description="Create a new Gmail label with optional custom colors. Returns the new label's ID.", inputSchema={ "type": "object", "properties": { "label_name": { "type": "string", "description": "Name for the new label. Use forward slashes for nested labels (e.g., 'Projects/Work')." }, "background_color": { "type": "string", "description": "Hex color code for label background (e.g., '#16a765'). Optional." }, "text_color": { "type": "string", "description": "Hex color code for label text (e.g., '#ffffff'). Optional." } }, "required": ["label_name"] }, ),
- GmailClient.create_label method: constructs label body with name and optional colors, calls Gmail API labels.create, returns success/error with label details.async def create_label(self, name: str, background_color: str | None = None, text_color: str | None = None) -> dict: """Create a new Gmail label. Args: name: Label name (can include / for nested labels) background_color: Optional hex color for background (e.g., '#16a765') text_color: Optional hex color for text (e.g., '#ffffff') Returns: The created label object """ try: label_body = { "name": name, "labelListVisibility": "labelShow", "messageListVisibility": "show", } if background_color or text_color: label_body["color"] = {} if background_color: label_body["color"]["backgroundColor"] = background_color if text_color: label_body["color"]["textColor"] = text_color result = self.service.users().labels().create( userId="me", body=label_body ).execute() logger.info(f"Created label: {name} (ID: {result['id']})") return {"success": True, "label": result} except HttpError as e: logger.error(f"Failed to create label: {e}") return {"success": False, "error": str(e)}
- src/mcp_gmail/server.py:1128-1131 (registration)Server registration: list_tools handler returns GMAIL_TOOLS list which includes the 'gmail_create_label' tool definition.@server.list_tools() async def list_tools() -> list[Tool]: return GMAIL_TOOLS