Gmail MCP Server

Instructions

Implementation Reference

• src/index.ts:262-296 (registration)

  Registration of the 'create_draft' MCP tool. Includes tool description, Zod input schema for parameters (raw, threadId, to, cc, bcc, subject, body, includeBodyHtml), and inline handler that uses handleTool to authenticate, construct raw message if needed, call Gmail drafts.create API, process response payload, and format output.
  server.tool("create_draft", "Create a draft email in Gmail. 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 draft 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 draftCreateParams: DraftCreateParams = { userId: 'me', requestBody: { message: { raw } } } if (params.threadId && draftCreateParams.requestBody?.message) { draftCreateParams.requestBody.message.threadId = params.threadId } const { data } = await gmail.users.drafts.create(draftCreateParams) if (data.message?.payload) { data.message.payload = processMessagePart( data.message.payload, params.includeBodyHtml ) } return formatResponse(data) }) } )
• src/index.ts:274-295 (handler)

  The handler function for the create_draft tool. It manages raw message construction if not provided, sets up the API request with optional threadId, executes gmail.users.drafts.create, processes the returned message payload, and returns formatted response.
  async (params) => { return handleTool(config, async (gmail: gmail_v1.Gmail) => { let raw = params.raw if (!raw) raw = await constructRawMessage(gmail, params) const draftCreateParams: DraftCreateParams = { userId: 'me', requestBody: { message: { raw } } } if (params.threadId && draftCreateParams.requestBody?.message) { draftCreateParams.requestBody.message.threadId = params.threadId } const { data } = await gmail.users.drafts.create(draftCreateParams) if (data.message?.payload) { data.message.payload = processMessagePart( data.message.payload, params.includeBodyHtml ) } return formatResponse(data) }) }
• src/index.ts:265-273 (schema)

  Zod schema defining the input parameters for the create_draft tool.
  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 draft 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:200-235 (helper)

  Key helper function used by create_draft (and send_message) to build the raw base64url-encoded RFC2822 email message. Fetches thread if threadId provided, constructs headers (To/Cc/Bcc/Subject/In-Reply-To/References), adds quoted thread history if applicable, wraps text for quoted-printable, encodes.
  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)

  Shared helper invoked by all tools' handlers. Creates/validates OAuth2 client, sets up Gmail client, executes the provided API callback, handles auth-specific errors with re-auth instructions, and formats general 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) { // 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}` }); } }