A1 AI engineering company GitHub
Connect the Gmail MCP server to your AI agent Open source, MIT, on npm. Setup instructions for Claude, Cursor and Codex are in the repository; adoption questions — Telegram. GitHub repository Telegram

Gmail: List labels — MCP tool

Gmail MCP tool: Lists every label in the mailbox, or fetches one label with its message counts.

Technical name: list_labels

What task it solves

I want to know what labels exist and what their ids are.

Labels are Gmail's folders, stars and read-state all at once; their ids are the vocabulary every filtering and filing tool speaks.

When to use it

Before any label_ids/add_label_ids usage, when the user names a label ("file it under Accounting") and its id is unknown, or with label_id to get unread/total counts for one label.

What to provide

  • label_id — optional. Fetch this one label including messagesTotal, messagesUnread, threadsTotal, threadsUnread (the plain list carries no counts).

What it returns

Without label_id: labels[] with id, name and type — system labels (INBOX, SENT, DRAFT, SPAM, TRASH, UNREAD, STARRED, IMPORTANT, CATEGORY_*) and user labels (Label_...). With label_id: that label with its counts.

What changes in Gmail

Nothing — a pure read.

Example request

How many unread messages are in my "Clients/Acme" label?

Errors and limitations

Counts require the per-label fetch — one call per label. User label ids are opaque (Label_123), never the display name; always resolve names through this tool. Access also depends on token permissions, quotas, and upstream API limits.

Related MCP tools

Technical details