list_messages

Instructions

Implementation Reference

• src/index.ts:580-608 (registration)

  Full registration of the 'list_messages' MCP tool, including description, input schema (Zod), and inline async handler function that invokes Gmail API.

  server.tool("list_messages",
    "List messages in the user's mailbox with optional filtering",
    {
      maxResults: z.number().optional().describe("Maximum number of messages to return. Accepts values between 1-500"),
      pageToken: z.string().optional().describe("Page token to retrieve a specific page of results"),
      q: z.string().optional().describe("Only return messages matching the specified query. Supports the same query format as the Gmail search box"),
      labelIds: z.array(z.string()).optional().describe("Only return messages with labels that match all of the specified label IDs"),
      includeSpamTrash: z.boolean().optional().describe("Include messages from SPAM and TRASH in the results"),
      includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large"),
    },
    async (params) => {
      return handleTool(config, async (gmail: gmail_v1.Gmail) => {
        const { data } = await gmail.users.messages.list({ userId: 'me', ...params })
  
        if (data.messages) {
          data.messages = data.messages.map((message: Message) => {
            if (message.payload) {
              message.payload = processMessagePart(
                message.payload,
                params.includeBodyHtml
              )
            }
            return message
          })
        }
  
        return formatResponse(data)
      })
    }

• src/index.ts:590-608 (handler)

  Handler function executes Gmail users.messages.list API call with user params, processes each message payload (decodes body if applicable, filters headers), and formats the response as JSON text content.

  async (params) => {
    return handleTool(config, async (gmail: gmail_v1.Gmail) => {
      const { data } = await gmail.users.messages.list({ userId: 'me', ...params })
  
      if (data.messages) {
        data.messages = data.messages.map((message: Message) => {
          if (message.payload) {
            message.payload = processMessagePart(
              message.payload,
              params.includeBodyHtml
            )
          }
          return message
        })
      }
  
      return formatResponse(data)
    })
  }

• src/index.ts:582-589 (schema)

  Input schema using Zod for validating parameters like maxResults, q (search query), labelIds, etc., passed to Gmail API.

  {
    maxResults: z.number().optional().describe("Maximum number of messages to return. Accepts values between 1-500"),
    pageToken: z.string().optional().describe("Page token to retrieve a specific page of results"),
    q: z.string().optional().describe("Only return messages matching the specified query. Supports the same query format as the Gmail search box"),
    labelIds: z.array(z.string()).optional().describe("Only return messages with labels that match all of the specified label IDs"),
    includeSpamTrash: z.boolean().optional().describe("Include messages from SPAM and TRASH in the results"),
    includeBodyHtml: z.boolean().optional().describe("Whether to include the parsed HTML in the return for each body, excluded by default because they can be excessively large"),
  },

• src/index.ts:80-94 (helper)

  Recursive helper to process message parts: decodes base64 bodies (except HTML unless flagged), recurses on parts, filters headers to response-relevant ones.

  const processMessagePart = (messagePart: MessagePart, includeBodyHtml = false): MessagePart => {
    if ((messagePart.mimeType !== 'text/html' || includeBodyHtml) && messagePart.body) {
      messagePart.body = decodedBody(messagePart.body)
    }
  
    if (messagePart.parts) {
      messagePart.parts = messagePart.parts.map(part => processMessagePart(part, includeBodyHtml))
    }
  
    if (messagePart.headers) {
      messagePart.headers = messagePart.headers.filter(header => RESPONSE_HEADERS_LIST.includes(header.name || ''))
    }
  
    return messagePart
  }

• src/index.ts:50-66 (helper)

  Shared helper wrapper for all tools: creates/validates OAuth2 client, builds Gmail client, executes provided API callback, handles errors.

  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}`
    }
  }