gmail-get-labels
Retrieve all Gmail labels to organize and categorize your email messages effectively for better inbox management.
Instructions
Get all Gmail labels
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Input Schema (JSON Schema)
{
"properties": {},
"type": "object"
}
Implementation Reference
- src/gmail.ts:368-407 (handler)The main handler function that authenticates with Gmail API using OAuth2, lists all labels for the user, maps the response to a simplified structure, formats them into Markdown using formatLabelsToMarkdown, and returns the result wrapped in MCP content format. Handles errors gracefully.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/index.ts:209-211 (registration)Registers the 'gmail-get-labels' tool with the MCP server. It has no input parameters (empty schema) and directly invokes the getLabels handler function.server.tool("gmail-get-labels", "Get all Gmail labels", {}, async () => { return await getLabels(); });
- src/gmail.ts:96-131 (helper)Helper function that formats the list of Gmail labels into a structured Markdown output, separating system and user labels, including counts of messages/threads and unread indicators.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 that creates and configures the OAuth2 client for Gmail API authentication using environment variables for credentials and tokens.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; }