Gmail MCP Server

Instructions

Implementation Reference

• src/index.ts:864-873 (registration)

  Registration of the 'get_pop' MCP tool. It has no input parameters (empty schema) and an inline handler function that uses the shared 'handleTool' to authenticate and call the Gmail API's users.settings.getPop method to retrieve POP settings, then formats the response.
  server.tool("get_pop", "Gets POP settings", {}, async () => { return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.settings.getPop({ userId: 'me' }) return formatResponse(data) }) } )
• src/index.ts:867-872 (handler)

  Handler function for 'get_pop' tool, which invokes the Gmail API to get POP settings after authentication via handleTool.
  async () => { return handleTool(config, async (gmail: gmail_v1.Gmail) => { const { data } = await gmail.users.settings.getPop({ userId: 'me' }) return formatResponse(data) }) }
• src/index.ts:50-80 (helper)

  Shared helper function 'handleTool' used by 'get_pop' (and other tools) to handle OAuth2 authentication, create Gmail client, execute the API call, and handle errors appropriately.
  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}` }); } }
• src/index.ts:48-48 (helper)

  Helper function 'formatResponse' used by 'get_pop' (and other tools) to format the API response as MCP content.
  const formatResponse = (response: any) => ({ content: [{ type: "text", text: JSON.stringify(response) }] })