batch_modify_messages

Instructions

Implementation Reference

• src/index.ts:514-527 (registration)

  Complete registration of the 'batch_modify_messages' MCP tool, including description, input schema (using Zod), and inline handler function. The handler wraps the Gmail API's users.messages.batchModify call with shared authentication and response formatting logic via handleTool and formatResponse.

  server.tool("batch_modify_messages",
    "Modify the labels on multiple messages",
    {
      ids: z.array(z.string()).describe("The IDs of the messages to modify"),
      addLabelIds: z.array(z.string()).optional().describe("A list of label IDs to add to the messages"),
      removeLabelIds: z.array(z.string()).optional().describe("A list of label IDs to remove from the messages")
    },
    async (params) => {
      return handleTool(config, async (gmail: gmail_v1.Gmail) => {
        const { data } = await gmail.users.messages.batchModify({ userId: 'me', requestBody: { ids: params.ids, addLabelIds: params.addLabelIds, removeLabelIds: params.removeLabelIds } })
        return formatResponse(data)
      })
    }
  )

• src/index.ts:521-526 (handler)

  The core handler logic for executing the batch_modify_messages tool: authenticates via handleTool, calls Gmail's batchModify API to add/remove labels from specified message IDs, and formats the response.

  async (params) => {
    return handleTool(config, async (gmail: gmail_v1.Gmail) => {
      const { data } = await gmail.users.messages.batchModify({ userId: 'me', requestBody: { ids: params.ids, addLabelIds: params.addLabelIds, removeLabelIds: params.removeLabelIds } })
      return formatResponse(data)
    })
  }

• src/index.ts:516-520 (schema)

  Zod schema defining input parameters for the batch_modify_messages tool: required array of message IDs, optional arrays for labels to add or remove.

  {
    ids: z.array(z.string()).describe("The IDs of the messages to modify"),
    addLabelIds: z.array(z.string()).optional().describe("A list of label IDs to add to the messages"),
    removeLabelIds: z.array(z.string()).optional().describe("A list of label IDs to remove from the messages")
  },

• src/index.ts:49-65 (helper)

  Shared helper function used by all Gmail tools, including batch_modify_messages, to handle OAuth2 authentication, credential validation, 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) {
      return `Tool execution failed: ${error.message}`
    }
  }

• src/index.ts:47-47 (helper)

  Shared helper that formats API responses into MCP-compatible content structure (JSON stringified as text). Used by batch_modify_messages handler.

  const formatResponse = (response: any) => ({ content: [{ type: "text", text: JSON.stringify(response) }] })