Gmail MCP

Instructions

Implementation Reference

• src/index.ts:702-717 (handler)

  Handler function for the 'get_thread' tool: fetches the thread by ID using Gmail API with format 'full', processes each message's payload by decoding bodies and filtering headers if includeBodyHtml is specified, then formats the response as JSON text.
  async (params) => { return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.threads.get({ userId: 'me', id: params.id, format: 'full' }) if (data.messages) { data.messages = data.messages.map(message => { if (message.payload) { message.payload = processMessagePart(message.payload, params.includeBodyHtml) } return message }) } return formatResponse(data) }) }
• src/index.ts:698-701 (schema)

  Zod schema defining input parameters for 'get_thread': required 'id' (thread ID string), optional 'includeBodyHtml' (boolean for including HTML bodies).
  { id: z.string().describe("The ID of the thread 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:696-718 (registration)

  Registration of the 'get_thread' MCP tool on the McpServer instance, specifying name, description, input schema, and handler function.
  server.tool("get_thread", "Get a specific thread by ID", { id: z.string().describe("The ID of the thread 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.threads.get({ userId: 'me', id: params.id, format: 'full' }) if (data.messages) { data.messages = data.messages.map(message => { if (message.payload) { message.payload = processMessagePart(message.payload, params.includeBodyHtml) } return message }) } return formatResponse(data) }) } )
• src/index.ts:49-65 (helper)

  Shared helper function used by all Gmail API tools, including get_thread: handles OAuth2 client creation/validation, Gmail client setup, 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:79-93 (helper)

  Recursive helper to process message parts: decodes base64 data to UTF-8 for non-HTML or specified HTML bodies, recurses on parts, filters headers to standard list (Date, From, To, etc.). Used in get_thread message processing.
  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 }