MCP Tools Reference: gmailmcp.googleapis.com

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' \
--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 MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for ListLabels RPC.

ListLabelsRequest

JSON representation 
{

  "pageSize": integer

  "pageToken": string
}
Fields

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 (Label)
    }
  ],
  "nextPageToken": string
}
Fields
labels[]

object (Label)

List of user labels in the user's account.
nextPageToken

string

Token to retrieve the next page of results in the list.

Label

JSON representation 
{
  "labelId": string,
  "name": string
}
Fields
labelId

string

The unique identifier of the label.
name

string

The human-readable display name of the label.

Tool Annotations

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌