gmail-get-labels
Retrieve all labels from a Gmail account to organize and categorize emails effectively.
Instructions
Get all Gmail labels
Tool call template
This tool declares no required parameters. Add optional parameters from the input schema as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {},
"name": "gmail-get-labels"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/gmail.ts:367-407 (handler)The core handler function that authenticates with Gmail API, lists all labels, maps them to a structured format, and returns formatted Markdown output or error.
// Get Gmail labels function 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, providing no input schema and delegating execution to the getLabels handler.
server.tool("gmail-get-labels", "Get all Gmail labels", {}, async () => { return await getLabels(); }); - src/gmail.ts:96-131 (helper)Helper function that formats the retrieved Gmail labels into a Markdown string, categorizing system and custom labels with unread/message 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 helper for creating OAuth2 authentication client used by all Gmail tools, reading 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; }