patch_label
Modify existing Gmail labels by updating their name, visibility settings, or color scheme to better organize your email inbox.
Instructions
Patch an existing label (partial update)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The ID of the label to patch | |
| name | No | The display name of the label | |
| messageListVisibility | No | The visibility of messages with this label in the message list | |
| labelListVisibility | No | The visibility of the label in the label list | |
| color | No | The color settings for the label |
Implementation Reference
- src/index.ts:492-511 (registration)Registration of the 'patch_label' tool using McpServer.tool(), including description, Zod input schema, and inline async handler that calls the Gmail API labels.patch method.server.tool("patch_label", "Patch an existing label (partial update)", { id: z.string().describe("The ID of the label to patch"), name: z.string().optional().describe("The display name of the label"), messageListVisibility: z.enum(['show', 'hide']).optional().describe("The visibility of messages with this label in the message list"), labelListVisibility: z.enum(['labelShow', 'labelShowIfUnread', 'labelHide']).optional().describe("The visibility of the label in the label list"), color: z.object({ textColor: z.string().describe("The text color of the label as hex string"), backgroundColor: z.string().describe("The background color of the label as hex string") }).optional().describe("The color settings for the label") }, async (params) => { const { id, ...labelData } = params return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.labels.patch({ userId: 'me', id, requestBody: labelData }) return formatResponse(data) }) } )
- src/index.ts:504-510 (handler)The core handler function for the patch_label tool. It destructures the label ID and update data from input params, then uses the shared handleTool utility to authenticate and execute the Gmail API users.labels.patch call, formatting the response.async (params) => { const { id, ...labelData } = params return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.labels.patch({ userId: 'me', id, requestBody: labelData }) return formatResponse(data) }) }
- src/index.ts:495-503 (schema)Zod schema defining the input parameters for the patch_label tool: required label ID, optional name, visibilities, and color object.id: z.string().describe("The ID of the label to patch"), name: z.string().optional().describe("The display name of the label"), messageListVisibility: z.enum(['show', 'hide']).optional().describe("The visibility of messages with this label in the message list"), labelListVisibility: z.enum(['labelShow', 'labelShowIfUnread', 'labelHide']).optional().describe("The visibility of the label in the label list"), color: z.object({ textColor: z.string().describe("The text color of the label as hex string"), backgroundColor: z.string().describe("The background color of the label as hex string") }).optional().describe("The color settings for the label") },
- src/index.ts:50-80 (helper)Shared helper function handleTool used by all Gmail API tools, including patch_label. Handles OAuth2 authentication, client validation, Gmail client creation, API call execution, error handling with auth-specific messages, and response formatting.const handleTool = async (queryConfig: Record<string, any> | undefined, apiCall: (gmail: gmail_v1.Gmail) => Promise<any>) => { try { const oauth2Client = queryConfig ? createOAuth2Client(queryConfig) : defaultOAuth2Client if (!oauth2Client) throw new Error('OAuth2 client could not be created, please check your credentials') const credentialsAreValid = await validateCredentials(oauth2Client) if (!credentialsAreValid) throw new Error('OAuth2 credentials are invalid, please re-authenticate') const gmailClient = queryConfig ? google.gmail({ version: 'v1', auth: oauth2Client }) : defaultGmailClient if (!gmailClient) throw new Error('Gmail client could not be created, please check your credentials') const result = await apiCall(gmailClient) return result } catch (error: any) { // Check for specific authentication errors if ( error.message?.includes("invalid_grant") || error.message?.includes("refresh_token") || error.message?.includes("invalid_client") || error.message?.includes("unauthorized_client") || error.code === 401 || error.code === 403 ) { return formatResponse({ error: `Authentication failed: ${error.message}. Please re-authenticate by running: npx @shinzolabs/gmail-mcp auth`, }); } return formatResponse({ error: `Tool execution failed: ${error.message}` }); } }