gmail-get-labels
Retrieve all labels from a Gmail account to organize and categorize emails using the MCP Server Boilerplate.
Instructions
Get all Gmail labels
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
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; }