MCP Server Boilerplate

Instructions

Implementation Reference

• src/index.ts:209-211 (registration)

  Registration of the 'gmail-get-labels' tool, which calls the getLabels function with no input parameters.

  server.tool("gmail-get-labels", "Get all Gmail labels", {}, async () => {
    return await getLabels();
  });

• src/gmail.ts:368-407 (handler)

  Main handler function that authenticates with Gmail API, fetches all labels, formats them using formatLabelsToMarkdown, and returns in MCP content format.

  export async function getLabels() {
    try {
      const auth = createGmailAuth();
      const gmail = google.gmail({ version: "v1", auth });
  
      const response = await gmail.users.labels.list({
        userId: "me",
      });
  
      const labels = response.data.labels?.map((label) => ({
        id: label.id,
        name: label.name,
        type: label.type,
        messagesTotal: label.messagesTotal,
        messagesUnread: label.messagesUnread,
        threadsTotal: label.threadsTotal,
        threadsUnread: label.threadsUnread,
      }));
  
      return {
        content: [
          {
            type: "text" as const,
            text: formatLabelsToMarkdown(labels || []),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error getting labels: ${
              error instanceof Error ? error.message : String(error)
            }`,
          },
        ],
      };
    }
  }

• src/gmail.ts:96-131 (helper)

  Helper function to format Gmail labels into a structured Markdown list, separating system and user labels with unread counts.

  function formatLabelsToMarkdown(labels: any[]): string {
    if (!labels.length) return "No labels found.";
    
    let markdown = `# Gmail Labels (${labels.length})\n\n`;
    
    const systemLabels = labels.filter(label => label.type === 'system');
    const userLabels = labels.filter(label => label.type === 'user');
    
    if (systemLabels.length) {
      markdown += `## System Labels\n\n`;
      systemLabels.forEach(label => {
        markdown += `- ${label.name} (\`${label.id}\`)`;
        if (label.messagesUnread > 0) {
          markdown += ` - ${label.messagesUnread} unread`;
        }
        markdown += `\n`;
      });
      markdown += `\n`;
    }
    
    if (userLabels.length) {
      markdown += `## Custom Labels\n\n`;
      userLabels.forEach(label => {
        markdown += `- ${label.name} (\`${label.id}\`)`;
        if (label.messagesTotal) {
          markdown += ` - ${label.messagesTotal} total`;
          if (label.messagesUnread > 0) {
            markdown += `, ${label.messagesUnread} unread`;
          }
        }
        markdown += `\n`;
      });
    }
    
    return markdown;
  }

• src/gmail.ts:134-165 (helper)

  Shared authentication helper for Gmail API using OAuth2 credentials from environment variables.

  function createGmailAuth() {
    const clientId = process.env.GOOGLE_CLIENT_ID;
    const clientSecret = process.env.GOOGLE_CLIENT_SECRET;
    const redirectUri =
      process.env.GOOGLE_REDIRECT_URI || "http://localhost:3000/oauth2callback";
  
    if (!clientId || !clientSecret) {
      throw new Error(
        "GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are required. Run oauth-setup.js to configure."
      );
    }
  
    const oauth2Client = new google.auth.OAuth2(
      clientId,
      clientSecret,
      redirectUri
    );
  
    const accessToken = process.env.GOOGLE_ACCESS_TOKEN;
    const refreshToken = process.env.GOOGLE_REFRESH_TOKEN;
  
    if (!accessToken || !refreshToken) {
      throw new Error("OAuth2 tokens missing. Run oauth-setup.js to get tokens.");
    }
  
    oauth2Client.setCredentials({
      access_token: accessToken,
      refresh_token: refreshToken,
    });
  
    return oauth2Client;
  }