modify_thread
Update email thread labels by adding or removing specific label IDs. Use this tool to organize and manage Gmail threads efficiently with precise control over labels.
Instructions
Modify the labels applied to a thread
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| addLabelIds | No | A list of label IDs to add to the thread | |
| id | Yes | The ID of the thread to modify | |
| removeLabelIds | No | A list of label IDs to remove from the thread |
Implementation Reference
- src/index.ts:789-803 (registration)Registration of the 'modify_thread' MCP tool, including input schema definition and handler function that calls Gmail API's threads.modify to update labels on a thread.server.tool("modify_thread", "Modify the labels applied to a thread", { id: z.string().describe("The ID of the thread to modify"), addLabelIds: z.array(z.string()).optional().describe("A list of label IDs to add to the thread"), removeLabelIds: z.array(z.string()).optional().describe("A list of label IDs to remove from the thread") }, async (params) => { const { id, ...threadData } = params return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.threads.modify({ userId: 'me', id, requestBody: threadData }) return formatResponse(data) }) } )
- src/index.ts:796-802 (handler)Handler function for 'modify_thread' tool. Extracts thread ID and label changes from params, uses handleTool wrapper to authenticate and call Gmail API's users.threads.modify method.async (params) => { const { id, ...threadData } = params return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.threads.modify({ userId: 'me', id, requestBody: threadData }) return formatResponse(data) }) }
- src/index.ts:792-795 (schema)Input schema for 'modify_thread' tool using Zod: requires thread ID, optional arrays for labels to add or remove.id: z.string().describe("The ID of the thread to modify"), addLabelIds: z.array(z.string()).optional().describe("A list of label IDs to add to the thread"), removeLabelIds: z.array(z.string()).optional().describe("A list of label IDs to remove from the thread") },
- src/index.ts:50-80 (helper)Shared 'handleTool' helper function used by 'modify_thread' and other tools for OAuth authentication, Gmail client creation, API call execution, and error handling.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}` }); } }
- src/index.ts:48-48 (helper)Utility function 'formatResponse' used to standardize tool responses as MCP content blocks with JSON-stringified data.const formatResponse = (response: any) => ({ content: [{ type: "text", text: JSON.stringify(response) }] })