Gmail MCP Server

Instructions

Implementation Reference

• src/index.ts:652-673 (handler)

  The handler function for the 'send_message' tool. It calls handleTool to authenticate, constructs a raw email message if not provided using constructRawMessage, sends it using the Gmail API's users.messages.send method, processes the response payload with processMessagePart if includeBodyHtml is specified, and formats the response.
  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:643-651 (schema)

  Input schema (Zod) for the 'send_message' tool defining parameters like raw, threadId, to, cc, bcc, subject, body, and includeBodyHtml.
  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:640-674 (registration)

  Registration of the 'send_message' tool on the MCP server using server.tool(), including description, input schema, and inline 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:200-235 (helper)

  Helper function constructRawMessage used by send_message to build the base64url-encoded raw RFC 2822 email message, handling recipients, subject, body, threading with quotes and headers.
  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-80 (helper)

  Core helper handleTool wraps API calls with OAuth2 client creation, credential validation, Gmail client setup, error handling (especially auth errors), and response formatting. Used by send_message.
  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) { // Check for specific authentication errors if ( error.message?.includes("invalid_grant") || error.message?.includes("refresh_token") || error.message?.includes("invalid_client") || error.message?.includes("unauthorized_client") || error.code === 401 || error.code === 403 ) { return formatResponse({ error: `Authentication failed: ${error.message}. Please re-authenticate by running: npx @shinzolabs/gmail-mcp auth`, }); } return formatResponse({ error: `Tool execution failed: ${error.message}` }); } }