Tool: list_labels
Lists all user-defined labels available in the authenticated user's Gmail account. Use this tool to discover the id
of a user label before calling label_thread
, unlabel_thread
, label_message
, or unlabel_message
. System labels are not returned by this tool but can be used with their well-known IDs: 'INBOX', 'TRASH', 'SPAM', 'STARRED', 'UNREAD', 'IMPORTANT', 'CHAT', 'DRAFT', 'SENT'.
The following sample demonstrate how to use curl
to invoke the list_labels
MCP tool.
| Curl Request |
|---|
curl --location 'https://gmailmcp.googleapis.com/mcp/v1' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "list_labels", "arguments": { // provide these details according to the tool' s MCP specification } } , "jsonrpc" : "2.0" , "id" : 1 } ' |
Input Schema
Request message for ListLabels RPC.
ListLabelsRequest
| JSON representation |
|---|
{ "pageSize" : integer "pageToken" : string } |
Union field _page_size
.
_page_size
can be only one of the following:
pageSize
integer
Optional. The maximum number of labels to return.
Union field _page_token
.
_page_token
can be only one of the following:
pageToken
string
Optional. Page token to retrieve a specific page of results in the list.
Output Schema
Response message for ListLabels RPC.
ListLabelsResponse
| JSON representation |
|---|
{
"labels"
:
[
{
object (
|
| Fields | |
|---|---|
labels[]
|
List of user labels in the user's account. |
nextPageToken
|
Token to retrieve the next page of results in the list. |
Label
| JSON representation |
|---|
{
"labelId"
:
string
,
"name"
:
string
,
"color"
:
{
object (
|
labelId
string
The unique identifier of the label.
name
string
The human-readable display name of the label.
color
object (
LabelColor
)
Optional. The color of the label.
Union field _threads_total
.
_threads_total
can be only one of the following:
threadsTotal
integer
The total number of threads under the label.
Union field _threads_unread
.
_threads_unread
can be only one of the following:
threadsUnread
integer
The number of unread threads under the label.
LabelColor
| JSON representation |
|---|
{ "textColor" : string , "backgroundColor" : string } |
| Fields | |
|---|---|
textColor
|
The text color of the label, represented as a hex string (e.g., "#000000"). |
backgroundColor
|
The background color of the label, represented as a hex string (e.g., "#ffffff"). |
Tool Annotations
Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌
