## Tool: `search_files`

> [!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.

Search for Drive files using a structured query (syntax: `query_term operator values`). Combine clauses with `and`, `or`, `not`, and parentheses. String values must be single-quoted; escape embedded quotes as `\'`.

Query terms \& operators:

- `title` (ops: contains, =, !=) --- file title
- `fullText` (ops: contains) --- title or body text
- `mimeType` (ops: contains, =, !=) --- MIME type
- `modifiedTime`, `viewedByMeTime`, `createdTime` (ops: `<=`, `<`, `=`, `!=`, `>`, `>=`). Use RFC 3339 UTC, e.g., `2012-06-04T12:00:00-08:00`. Date types not comparable.
- `parentId` (ops: `=`, `!=`). Use `'root'` for the user's "My Drive".
- `owner` (ops: `=`, `!=`). Use `'me'` for the requesting user.
- `sharedWithMe` (ops: `=`, `!=`). Values: `true` or `false`.

Other operators: `and`, `or`, `not`.

Examples:

- `title contains 'hello' and title contains 'goodbye'`
- `modifiedTime > '2024-01-01T00:00:00Z' and (mimeType contains 'image/' or mimeType contains 'video/')`
- `parentId = '1234567'`
- `fullText contains 'hello'`
- `owner = 'test@example.org'`
- `sharedWithMe = true`
- `owner = 'me'` (for files owned by the user)

Use `next_page_token` to paginate. An empty response means no more results.

The following sample demonstrate how to use `curl` to invoke the `search_files` MCP tool.

| Curl Request |
|---|
| ```bash curl --location 'https://drivemcp.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": "search_files", "arguments": { // provide these details according to the tool's MCP specification } }, "jsonrpc": "2.0", "id": 1 }' ``` |

## Input Schema

Request to search files.

### SearchFilesRequest

| JSON representation |
|---|
| ``` { "query": string, "pageToken": string "pageSize": integer "excludeContentSnippets": boolean } ``` |

| Fields ||
|---|---|
| `query` | `string` The search query. |
| Union field `_page_token`. `_page_token` can be only one of the following: ||
| `pageToken` | `string` The page token to use for pagination. |
| Union field `_page_size`. `_page_size` can be only one of the following: ||
| `pageSize` | `integer` The maximum number of files to return in each page. |
| Union field `_exclude_content_snippets`. `_exclude_content_snippets` can be only one of the following: ||
| `excludeContentSnippets` | `boolean` If true, the content snippet will be excluded from the response. |

## Output Schema

Response to search files.

### SearchFilesResponse

| JSON representation |
|---|
| ``` { "files": [ { object (`https://developers.google.com/workspace/drive/api/reference/mcp/tools_list/copy_file#Output.Schema.File`) } ], "nextPageToken": string } ``` |

| Fields ||
|---|---|
| `files[]` | ``object (`https://developers.google.com/workspace/drive/api/reference/mcp/tools_list/copy_file#Output.Schema.File`)`` Output only. The list of files. |
| Union field `_next_page_token`. `_next_page_token` can be only one of the following: ||
| `nextPageToken` | `string` The next page token. |

### File

| JSON representation |
|---|
| ``` { "id": string, "title": string, "parentId": string, "mimeType": string "fileSize": string "description": string "fileExtension": string "contentSnippet": string "viewUrl": string "sharedWithMeTime": string "createdTime": string "modifiedTime": string "viewedByMeTime": string "owner": string "canAddChildren": boolean } ``` |

| Fields ||
|---|---|
| `id` | `string` The id of the file that was fetched. |
| `title` | `string` The title of the file. |
| `parentId` | `string` The (optional) id of the parent of the file. |
| Union field `_mime_type`. `_mime_type` can be only one of the following: ||
| `mimeType` | `string` The mime type of the file. |
| Union field `_file_size`. `_file_size` can be only one of the following: ||
| `fileSize` | `string (https://developers.google.com/discovery/v1/type-format format)` The size in bytes of the file. |
| Union field `_description`. `_description` can be only one of the following: ||
| `description` | `string` The description of the file. |
| Union field `_file_extension`. `_file_extension` can be only one of the following: ||
| `fileExtension` | `string` The original file extension of the file, this is only populated for files with content stored in Drive. |
| Union field `_content_snippet`. `_content_snippet` can be only one of the following: ||
| `contentSnippet` | `string` Generated snippet about the content of the file. |
| Union field `_view_url`. `_view_url` can be only one of the following: ||
| `viewUrl` | `string` The URL to view the file. |
| Union field `_shared_with_me_time`. `_shared_with_me_time` can be only one of the following: ||
| `sharedWithMeTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` The time that the file was shared with the requester. 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"`. |
| Union field `_created_time`. `_created_time` can be only one of the following: ||
| `createdTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` The time that the file was created. 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"`. |
| Union field `_modified_time`. `_modified_time` can be only one of the following: ||
| `modifiedTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` The most recent time at which the file was modified. 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"`. |
| Union field `_viewed_by_me_time`. `_viewed_by_me_time` can be only one of the following: ||
| `viewedByMeTime` | ``string (`https://protobuf.dev/reference/protobuf/google.protobuf#timestamp` format)`` The most recent time at which the file was viewed by requester. 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"`. |
| Union field `_owner`. `_owner` can be only one of the following: ||
| `owner` | `string` The email address of the owner of the file. |
| Union field `_can_add_children`. `_can_add_children` can be only one of the following: ||
| `canAddChildren` | `boolean` Whether the requester can add children to this folder. This is always false for non-folder types. |

### 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. |

### Tool Annotations

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

## Authorization Scopes

Requires one of the following OAuth scopes:

- `https://www.googleapis.com/auth/drive`
- `https://www.googleapis.com/auth/drive.appdata`
- `https://www.googleapis.com/auth/drive.file`
- `https://www.googleapis.com/auth/drive.meet.readonly`
- `https://www.googleapis.com/auth/drive.metadata`
- `https://www.googleapis.com/auth/drive.metadata.readonly`
- `https://www.googleapis.com/auth/drive.photos.readonly`
- `https://www.googleapis.com/auth/drive.readonly`