## Tool: `list_labels`

> [!WARNING]
> **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview), which grants early access to certain features.

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 |
|---|
| ```bash curl --location 'https://gmailmcp.googleapis.com/mcp/v1' \ --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \ --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 } ``` |

| 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 (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/list_labels#Output.Schema.Label`) } ], "nextPageToken": string } ``` |

| Fields ||
|---|---|
| `labels[]` | ``object (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/list_labels#Output.Schema.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, "color": { object (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/list_labels#Output.Schema.LabelColor`) }, "threadsTotal": integer "threadsUnread": integer } ``` |

| Fields ||
|---|---|
| `labelId` | `string` The unique identifier of the label. |
| `name` | `string` The human-readable display name of the label. |
| `color` | ``object (`https://developers.google.com/workspace/gmail/api/reference/mcp/tools_list/list_labels#Output.Schema.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` | `string` The text color of the label, represented as a hex string (e.g., "#000000"). Only the following predefined set of color values are allowed: `#000000`, `#434343`, `#666666`, `#999999`, `#cccccc`, `#efefef`, `#f3f3f3`, `#ffffff`, `#fb4c2f`, `#ffad47`, `#fad165`, `#16a766`, `#43d692`, `#4a86e8`, `#a479e2`, `#f691b3`, `#f6c5be`, `#ffe6c7`, `#fef1d1`, `#b9e4d0`, `#c6f3de`, `#c9daf8`, `#e4d7f5`, `#fcdee8`, `#efa093`, `#ffd6a2`, `#fce8b3`, `#89d3b2`, `#a0eac9`, `#a4c2f4`, `#d0bcf1`, `#fbc8d9`, `#e66550`, `#ffbc6b`, `#fcda83`, `#44b984`, `#68dfa9`, `#6d9eeb`, `#b694e8`, `#f7a7c0`, `#cc3a21`, `#eaa041`, `#f2c960`, `#149e60`, `#3dc789`, `#3c78d8`, `#8e63ce`, `#e07798`, `#ac2b16`, `#cf8933`, `#d5ae49`, `#0b804b`, `#2a9c68`, `#285bac`, `#653e9b`, `#b65775`, `#822111`, `#a46a21`, `#aa8831`, `#076239`, `#1a764d`, `#1c4587`, `#41236d`, `#83334c`, `#464646`, `#e7e7e7`, `#0d3472`, `#b6cff5`, `#0d3b44`, `#98d7e4`, `#3d188e`, `#e3d7ff`, `#711a36`, `#fbd3e0`, `#8a1c0a`, `#f2b2a8`, `#7a2e0b`, `#ffc8af`, `#7a4706`, `#ffdeb5`, `#594c05`, `#fbe983`, `#684e07`, `#fdedc1`, `#0b4f30`, `#b3efd3`, `#04502e`, `#a2dcc1`, `#c2c2c2`, `#4986e7`, `#2da2bb`, `#b99aff`, `#994a64`, `#f691b2`, `#ff7537`, `#ffad46`, `#662e37`, `#ebdbde`, `#cca6ac`, `#094228`, `#42d692`, `#16a765` |
| `backgroundColor` | `string` The background color of the label, represented as a hex string (e.g., "#ffffff"). Only the following predefined set of color values are allowed: `#000000`, `#434343`, `#666666`, `#999999`, `#cccccc`, `#efefef`, `#f3f3f3`, `#ffffff`, `#fb4c2f`, `#ffad47`, `#fad165`, `#16a766`, `#43d692`, `#4a86e8`, `#a479e2`, `#f691b3`, `#f6c5be`, `#ffe6c7`, `#fef1d1`, `#b9e4d0`, `#c6f3de`, `#c9daf8`, `#e4d7f5`, `#fcdee8`, `#efa093`, `#ffd6a2`, `#fce8b3`, `#89d3b2`, `#a0eac9`, `#a4c2f4`, `#d0bcf1`, `#fbc8d9`, `#e66550`, `#ffbc6b`, `#fcda83`, `#44b984`, `#68dfa9`, `#6d9eeb`, `#b694e8`, `#f7a7c0`, `#cc3a21`, `#eaa041`, `#f2c960`, `#149e60`, `#3dc789`, `#3c78d8`, `#8e63ce`, `#e07798`, `#ac2b16`, `#cf8933`, `#d5ae49`, `#0b804b`, `#2a9c68`, `#285bac`, `#653e9b`, `#b65775`, `#822111`, `#a46a21`, `#aa8831`, `#076239`, `#1a764d`, `#1c4587`, `#41236d`, `#83334c`, `#464646`, `#e7e7e7`, `#0d3472`, `#b6cff5`, `#0d3b44`, `#98d7e4`, `#3d188e`, `#e3d7ff`, `#711a36`, `#fbd3e0`, `#8a1c0a`, `#f2b2a8`, `#7a2e0b`, `#ffc8af`, `#7a4706`, `#ffdeb5`, `#594c05`, `#fbe983`, `#684e07`, `#fdedc1`, `#0b4f30`, `#b3efd3`, `#04502e`, `#a2dcc1`, `#c2c2c2`, `#4986e7`, `#2da2bb`, `#b99aff`, `#994a64`, `#f691b2`, `#ff7537`, `#ffad46`, `#662e37`, `#ebdbde`, `#cca6ac`, `#094228`, `#42d692`, `#16a765` |

### Tool Annotations

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

## Authorization Scopes

Requires one of the following OAuth scopes:

- `https://mail.google.com/`
- `https://www.googleapis.com/auth/gmail.modify`
- `https://www.googleapis.com/auth/gmail.readonly`
- `https://www.googleapis.com/auth/gmail.labels`
- `https://www.googleapis.com/auth/gmail.metadata`