## Tool: `list_objects`

Lists the objects in a bucket.

The following code sample shows how to use `curl` to call the `list_objects` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://storage.googleapis.com/storage/mcp' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "list_objects", "arguments": { // Provide these details according to the MCP tool specification. } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

### ListObjectsRequest

| JSON representation |
|---|
| ``` { "bucketName": string, "prefix": string, "recursive": boolean, "pageSize": integer, "pageToken": string } ``` |

| Fields ||
|---|---|
| `bucketName` | `string` Required. The name of the bucket to list objects in. Format: {bucket_id} |
| `prefix` | `string` Optional. The prefix to filter objects by. If not specified, all objects are matched. If `recursive` is `false`, only objects at the same level as the prefix are matched. For instance, if `recursive` is `false`, `"documents"` will match `"documents.txt"` but not `"documents/my-file.txt"`. |
| `recursive` | `boolean` Optional. Indicates whether the list operation should be recursive, including objects in subdirectories. If false (default), only objects directly within the specified prefix are listed. |
| `pageSize` | `integer` Optional. The maximum number of objects to return. The service can return fewer than this value. If unspecified, at most 1000 objects will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
| `pageToken` | `string` Optional. A page token, received from a previous `ListObjects` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListObjects` must match the call that provided the page token (except `pageSize`, which can differ). |

## Output Schema

Response message for ListObjects.

### ListObjectsResponse

| JSON representation |
|---|
| ``` { "objectNames": [ string ], "prefixes": [ string ], "nextPageToken": string, "objects": [ { object (`https://docs.cloud.google.com/storage/docs/reference/mcp/tools_list/list_objects#Output.Schema.Object`) } ] } ``` |

| Fields ||
|---|---|
| `objectNames[]` | `string` The list of objects, ordered lexicographically by name. At most 1000 objects are returned. |
| `prefixes[]` | `string` Object name prefixes for objects that matched the listing request but were excluded from `objectNames` because `recursive` is `false`. Values in this list are object names up to and including the delimiter `/`. Duplicate entries are omitted from this list. Ordered lexicographically. At most 1000 prefixes are returned. |
| `nextPageToken` | `string` A token, which can be sent as `pageToken` to retrieve the next page. If this field is omitted, there are no subsequent pages. |
| `objects[]` | ``object (`https://docs.cloud.google.com/storage/docs/reference/mcp/tools_list/list_objects#Output.Schema.Object`)`` Detailed metadata for the returned objects. |

### Object

| JSON representation |
|---|
| ``` { "bucketName": string, "objectName": string, "contentType": string, "size": string, "storageClass": string, "timeCreated": string, "timeLastModified": string, "generation": string, "metageneration": string, "etag": string, "checksums": { object (`https://docs.cloud.google.com/storage/docs/reference/mcp/tools_list/list_objects#Output.Schema.ObjectChecksumsMetadata`) }, "contentEncoding": string, "contentDisposition": string, "contentLanguage": string, "cacheControl": string, "customTime": string, "softDeleteTime": string, "retentionExpireTime": string, "kmsKeyName": string, "customerEncryption": { object (`https://docs.cloud.google.com/storage/docs/reference/mcp/tools_list/list_objects#Output.Schema.CustomerEncryptionMetadata`) }, "temporaryHold": boolean, "eventBasedHold": boolean, "retention": { object (`https://docs.cloud.google.com/storage/docs/reference/mcp/tools_list/list_objects#Output.Schema.ObjectRetentionMetadata`) }, "metadata": { string: string, ... }, "componentCount": integer } ``` |

| Fields ||
|---|---|
| `bucketName` | `string` The name of the bucket containing this object. |
| `objectName` | `string` The name of this object. Nearly any sequence of unicode characters is valid. See [Guidelines](https://docs.cloud.google.com/storage/docs/objects#naming). |
| `contentType` | `string` Content-Type of the object data, matching [RFC 7231 §3.1.1.5](https://tools.ietf.org/html/rfc7231#section-3.1.1.5). If an object is stored without a Content-Type, it is served as `application/octet-stream`. |
| `size` | `string (https://developers.google.com/discovery/v1/type-format format)` Content-Length of the object data in bytes, matching [RFC 7230 §3.3.2](https://tools.ietf.org/html/rfc7230#section-3.3.2). |
| `storageClass` | `string` Storage class of the object. |
| `timeCreated` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` The creation time of the object. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `timeLastModified` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` The modification time of the object metadata. Set initially to object creation time and then updated whenever any metadata of the object changes. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `generation` | `string (https://developers.google.com/discovery/v1/type-format format)` The content generation of this object. Used for object versioning. |
| `metageneration` | `string (https://developers.google.com/discovery/v1/type-format format)` The version of the metadata for this generation of this object. Used for preconditions and for detecting changes in metadata. |
| `etag` | `string` The `etag` of an object. |
| `checksums` | ``object (`https://docs.cloud.google.com/storage/docs/reference/mcp/tools_list/list_objects#Output.Schema.ObjectChecksumsMetadata`)`` Hashes for the data part of this object. |
| `contentEncoding` | `string` Content-Encoding of the object data, matching [RFC 7231 §3.1.2.2](https://tools.ietf.org/html/rfc7231#section-3.1.2.2). |
| `contentDisposition` | `string` Content-Disposition of the object data, matching [RFC 6266](https://tools.ietf.org/html/rfc6266). |
| `contentLanguage` | `string` Content-Language of the object data, matching [RFC 7231 §3.1.3.2](https://tools.ietf.org/html/rfc7231#section-3.1.3.2). |
| `cacheControl` | `string` Cache-Control directive for the object data, matching [RFC 7234 §5.2](https://tools.ietf.org/html/rfc7234#section-5.2). If omitted, and the object is accessible to all anonymous users, the default is `public, max-age=3600`. |
| `customTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` A user-specified timestamp set on an object. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `softDeleteTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` The time when the object became soft-deleted. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `retentionExpireTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` A server-determined value that specifies the earliest time that the object's retention period expires. Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |
| `kmsKeyName` | `string` Cloud KMS Key used to encrypt this object, if the object is encrypted by such a key. |
| `customerEncryption` | ``object (`https://docs.cloud.google.com/storage/docs/reference/mcp/tools_list/list_objects#Output.Schema.CustomerEncryptionMetadata`)`` Metadata of customer-supplied encryption key, if the object is encrypted by such a key. |
| `temporaryHold` | `boolean` Whether an object is under temporary hold. While this flag is set to true, the object is protected against deletion and overwrites. |
| `eventBasedHold` | `boolean` Whether an object is under event-based hold. |
| `retention` | ``object (`https://docs.cloud.google.com/storage/docs/reference/mcp/tools_list/list_objects#Output.Schema.ObjectRetentionMetadata`)`` Retention configuration of this object. |
| `metadata` | `map (key: string, value: string)` User-provided metadata, in key/value pairs. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |
| `componentCount` | `integer` Number of underlying components that make up this object. Components are accumulated by compose operations. |

### Timestamp

| JSON representation |
|---|
| ``` { "seconds": string, "nanos": integer } ``` |

| Fields ||
|---|---|
| `seconds` | `string (https://developers.google.com/discovery/v1/type-format format)` Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be between -62135596800 and 253402300799 inclusive (which corresponds to 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z). |
| `nanos` | `integer` Non-negative fractions of a second at nanosecond resolution. This field is the nanosecond portion of the duration, not an alternative to seconds. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be between 0 and 999,999,999 inclusive. |

### ObjectChecksumsMetadata

| JSON representation |
|---|
| ``` { "md5Hash": string, // Union field `_crc32c` can be only one of the following: "crc32c": integer // End of list of possible types for union field `_crc32c`. } ``` |

| Fields ||
|---|---|
| `md5Hash` | `string (https://developers.google.com/discovery/v1/type-format format)` A base64-encoded string. |
| Union field `_crc32c`. `_crc32c` can be only one of the following: ||
| `crc32c` | `integer` |
|   ||

### CustomerEncryptionMetadata

| JSON representation |
|---|
| ``` { "encryptionAlgorithm": string, "keySha256Bytes": string } ``` |

| Fields ||
|---|---|
| `encryptionAlgorithm` | `string` |
| `keySha256Bytes` | `string (https://developers.google.com/discovery/v1/type-format format)` A base64-encoded string. |

### ObjectRetentionMetadata

| JSON representation |
|---|
| ``` { "mode": enum (`https://docs.cloud.google.com/storage/docs/reference/mcp/tools_list/list_objects#Output.Schema.Mode`), "retainUntilTime": string } ``` |

| Fields ||
|---|---|
| `mode` | ``enum (`https://docs.cloud.google.com/storage/docs/reference/mcp/tools_list/list_objects#Output.Schema.Mode`)`` |
| `retainUntilTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: `"2014-10-02T15:01:23Z"`, `"2014-10-02T15:01:23.045123456Z"` or `"2014-10-02T15:01:23+05:30"`. |

### MetadataEntry

| JSON representation |
|---|
| ``` { "key": string, "value": string } ``` |

| Fields ||
|---|---|
| `key` | `string` |
| `value` | `string` |

### Mode

| Enums ||
|---|---|
| `MODE_UNSPECIFIED` |   |
| `UNLOCKED` |   |
| `LOCKED` |   |

### Tool Annotations


[Tool annotations](https://modelcontextprotocol.io/specification/latest/schema#toolannotations) are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.


Along with the title string, the following boolean hints are defined as follows:

- `readOnlyHint`: If true, the tool doesn't modify its environment. Default: false.
- `destructiveHint`: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
- `idempotentHint`: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
- `openWorldHint`: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

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