gmail-get-labels
Retrieve all Gmail labels programmatically using this tool. Integrate with MCP Server Boilerplate to manage and automate email labeling workflows efficiently.
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 on the MCP server, which delegates to the getLabels() function.server.tool("gmail-get-labels", "Get all Gmail labels", {}, async () => { return await getLabels(); });
- src/gmail.ts:368-407 (handler)Core handler function that authenticates with Gmail API, lists all labels, formats them into Markdown, and returns the response in MCP 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 the list of Gmail labels into a structured Markdown response, separating system and user labels.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)Helper function to create OAuth2 authentication client for Gmail API using 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; }