Gmail MCP Server

Instructions

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"]
      },
  ),

• src/mcp_gmail/gmail_client.py:389-425 (helper)

  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