## Tool: `get_values`

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

Returns a range of values from a spreadsheet.

Corresponds to spreadsheets.values.get in the REST API: <https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/get>

Schema: - `spreadsheet_id` (string, required): The ID of the spreadsheet to retrieve data from. - `range` (string, required): The A1 notation or R1C1 notation of the range to retrieve values from (e.g. `"Sheet1!A1:B10"`).

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

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

## Input Schema

### GetValuesRequest

| JSON representation |
|---|
| ``` { "spreadsheetId": string, "range": string } ``` |

| Fields ||
|---|---|
| `spreadsheetId` | `string` Required. The ID of the spreadsheet to retrieve data from. |
| `range` | `string` Required. The [A1 notation or R1C1 notation](https://developers.google.com/workspace/sheets/api/guides/concepts) of the range to retrieve values from. |

## Output Schema

Data within a range of the spreadsheet. <https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values>

### ValueRange

| JSON representation |
|---|
| ``` { "range": string, "values": [ array ] } ``` |

| Fields ||
|---|---|
| `range` | `string` The range the values cover, in [A1 notation](https://developers.google.com/workspace/sheets/api/guides/concepts). |
| `values[]` | ``array (`https://protobuf.dev/reference/protobuf/google.protobuf#list-value` format)`` The data that was read. This is an array of arrays, the outer array representing all the data and each inner array representing a row. Each item in the inner array corresponds with one cell. Empty trailing rows and columns will not be included. |

### ListValue

| JSON representation |
|---|
| ``` { "values": [ value ] } ``` |

| Fields ||
|---|---|
| `values[]` | ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` Repeated field of dynamically typed values. |

### Value

| JSON representation |
|---|
| ``` { "nullValue": null, "numberValue": number, "stringValue": string, "boolValue": boolean, "structValue": { object }, "listValue": array } ``` |

| Fields ||
|---|---|
| Union field `kind`. The kind of value. `kind` can be only one of the following: ||
| `nullValue` | `null` Represents a JSON `null`. |
| `numberValue` | `number` Represents a JSON number. Must not be `NaN`, `Infinity` or `-Infinity`, since those are not supported in JSON. This also cannot represent large Int64 values, since JSON format generally does not support them in its number type. |
| `stringValue` | `string` Represents a JSON string. |
| `boolValue` | `boolean` Represents a JSON boolean (`true` or `false` literal in JSON). |
| `structValue` | ``object (`https://protobuf.dev/reference/protobuf/google.protobuf#struct` format)`` Represents a JSON object. |
| `listValue` | ``array (`https://protobuf.dev/reference/protobuf/google.protobuf#list-value` format)`` Represents a JSON array. |
|   ||

### Struct

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

| Fields ||
|---|---|
| `fields` | ``map (key: string, value: value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format))`` Unordered map of dynamically typed values. An object containing a list of `"key": value` pairs. Example: `{ "name": "wrench", "mass": "1.3kg", "count": "3" }`. |

### FieldsEntry

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

| Fields ||
|---|---|
| `key` | `string` |
| `value` | ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` |

### NullValue

Represents a JSON `null`.

`NullValue` is a sentinel, using an enum with only one value to represent the null value for the `Value` type union.

A field of type `NullValue` with any value other than `0` is considered invalid. Most ProtoJSON serializers will emit a `Value` with a `null_value` set as a JSON `null` regardless of the integer value, and so will round trip to a `0` value.

| Enums ||
|---|---|
| `NULL_VALUE` | Null value. |

### 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: ✅

## Authorization Scopes

Requires one of the following OAuth scopes:

- `https://www.googleapis.com/auth/drive.readonly`
- `https://www.googleapis.com/auth/spreadsheets.readonly`
- `https://www.googleapis.com/auth/drive`
- `https://www.googleapis.com/auth/drive.file`
- `https://www.googleapis.com/auth/spreadsheets`