Gmail MCP

Instructions

Implementation Reference

• src/index.ts:575-591 (registration)

  Registration of the 'get_message' MCP tool using McpServer.tool(), including description, input schema validation with Zod, and the handler function.

  server.tool("get_message",
    "Get a specific message by ID with format options",
    {
      id: z.string().describe("The ID of the message to retrieve"),
      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.get({ userId: 'me', id: params.id, format: 'full' })
  
        if (data.payload) {
          data.payload = processMessagePart(data.payload, params.includeBodyHtml)
        }
  
        return formatResponse(data)
      })
    }

• src/index.ts:581-591 (handler)

  Handler function for the get_message tool. Fetches the Gmail message by ID using the Gmail API with full format, processes the payload (decodes body, handles parts, filters headers), and returns formatted JSON response.

  async (params) => {
    return handleTool(config, async (gmail: gmail_v1.Gmail) => {
      const { data } = await gmail.users.messages.get({ userId: 'me', id: params.id, format: 'full' })
  
      if (data.payload) {
        data.payload = processMessagePart(data.payload, params.includeBodyHtml)
      }
  
      return formatResponse(data)
    })
  }

• src/index.ts:577-580 (schema)

  Zod input schema for get_message tool: requires 'id' (message ID string), optional 'includeBodyHtml' boolean.

  {
    id: z.string().describe("The ID of the message to retrieve"),
    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:94-108 (helper)

  Recursive helper to process Gmail message parts: decodes base64 bodies (text/plain/html if allowed), recurses on parts, filters to essential headers.

  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:82-92 (helper)

  Helper to decode base64url-encoded message body data to UTF-8 string, used in processMessagePart.

  const decodedBody = (body: MessagePartBody) => {
    if (!body?.data) return body
  
    const decodedData = Buffer.from(body.data, 'base64').toString('utf-8')
    const decodedBody: MessagePartBody = {
      data: decodedData,
      size: body.data.length,
      attachmentId: body.attachmentId
    }
    return decodedBody
  }