Gmail MCP Server

Instructions

Implementation Reference

• src/index.ts:638-659 (handler)

  The handler function for the 'send_message' tool. It constructs a raw email message if not provided using constructRawMessage, sends it via the Gmail API's users.messages.send method, processes the returned message payload to decode bodies and filter headers, and formats the response as JSON text content.
  async (params) => { return handleTool(config, async (gmail: gmail_v1.Gmail) => { let raw = params.raw if (!raw) raw = await constructRawMessage(gmail, params) const messageSendParams: MessageSendParams = { userId: 'me', requestBody: { raw } } if (params.threadId && messageSendParams.requestBody) { messageSendParams.requestBody.threadId = params.threadId } const { data } = await gmail.users.messages.send(messageSendParams) if (data.payload) { data.payload = processMessagePart( data.payload, params.includeBodyHtml ) } return formatResponse(data) }) }
• src/index.ts:629-637 (schema)

  Zod schema defining the input parameters for the 'send_message' tool, including optional raw message, threadId, recipients (to, cc, bcc), subject, body, and flag for including HTML body.
  raw: z.string().optional().describe("The entire email message in base64url encoded RFC 2822 format, ignores params.to, cc, bcc, subject, body, includeBodyHtml if provided"), threadId: z.string().optional().describe("The thread ID to associate this message with"), to: z.array(z.string()).optional().describe("List of recipient email addresses"), cc: z.array(z.string()).optional().describe("List of CC recipient email addresses"), bcc: z.array(z.string()).optional().describe("List of BCC recipient email addresses"), subject: z.string().optional().describe("The subject of the email"), body: z.string().optional().describe("The body of the email"), 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:626-660 (registration)

  Registration of the 'send_message' tool on the McpServer instance, including name, description, input schema, and handler function.
  server.tool("send_message", "Send an email message to specified recipients. Note the mechanics of the raw parameter.", { raw: z.string().optional().describe("The entire email message in base64url encoded RFC 2822 format, ignores params.to, cc, bcc, subject, body, includeBodyHtml if provided"), threadId: z.string().optional().describe("The thread ID to associate this message with"), to: z.array(z.string()).optional().describe("List of recipient email addresses"), cc: z.array(z.string()).optional().describe("List of CC recipient email addresses"), bcc: z.array(z.string()).optional().describe("List of BCC recipient email addresses"), subject: z.string().optional().describe("The subject of the email"), body: z.string().optional().describe("The body of the email"), 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) => { let raw = params.raw if (!raw) raw = await constructRawMessage(gmail, params) const messageSendParams: MessageSendParams = { userId: 'me', requestBody: { raw } } if (params.threadId && messageSendParams.requestBody) { messageSendParams.requestBody.threadId = params.threadId } const { data } = await gmail.users.messages.send(messageSendParams) if (data.payload) { data.payload = processMessagePart( data.payload, params.includeBodyHtml ) } return formatResponse(data) }) } )
• src/index.ts:186-221 (helper)

  Helper function to construct the raw base64url-encoded RFC 2822 email message from parameters, handling thread quoting, headers, and body wrapping.
  const constructRawMessage = async (gmail: gmail_v1.Gmail, params: NewMessage) => { let thread: Thread | null = null if (params.threadId) { const threadParams = { userId: 'me', id: params.threadId, format: 'full' } const { data } = await gmail.users.threads.get(threadParams) thread = data } const message = [] if (params.to?.length) message.push(`To: ${wrapTextBody(params.to.join(', '))}`) if (params.cc?.length) message.push(`Cc: ${wrapTextBody(params.cc.join(', '))}`) if (params.bcc?.length) message.push(`Bcc: ${wrapTextBody(params.bcc.join(', '))}`) if (thread) { message.push(...getThreadHeaders(thread).map(header => wrapTextBody(header))) } else if (params.subject) { message.push(`Subject: ${wrapTextBody(params.subject)}`) } else { message.push('Subject: (No Subject)') } message.push('Content-Type: text/plain; charset="UTF-8"') message.push('Content-Transfer-Encoding: quoted-printable') message.push('MIME-Version: 1.0') message.push('') if (params.body) message.push(wrapTextBody(params.body)) if (thread) { const quotedContent = getQuotedContent(thread) if (quotedContent) { message.push('') message.push(wrapTextBody(quotedContent)) } } return Buffer.from(message.join('\r\n')).toString('base64url').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '') }
• src/index.ts:50-66 (helper)

  Shared helper function that handles OAuth2 authentication, client creation, and execution of Gmail API calls for all tools, with 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}` } }