MCP Tools Reference: sheetsmcp.googleapis.com

工具：get_spreadsheet

返回指定电子表格的电子表格内容。返回指定电子表格 ID 的标题、工作表名称、网格属性和其他元数据。如果请求，还会返回完整的网格数据。

对应于 REST API 中的 spreadsheets.get：https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/get

架构：- spreadsheet_id（字符串，必需）：要请求的电子表格的 ID。- include_grid_data（布尔值，可选）：如果应返回网格数据，则为 True。默认值为 false。- fields（字符串数组，可选）：指定要返回的属性的字段掩码（例如 ["sheets.properties.sheetId", "sheets.properties.title"]）。- comments_included（布尔值，可选）：如果为 true，则响应中将包含注释。默认值为 false。- ranges（字符串数组，可选）：要从电子表格中检索的 A1 或 R1C1 范围。如果未指定，则返回整个电子表格。

以下代码示例展示了如何使用 curl 调用 get_spreadsheet MCP 工具。

Curl 请求 
curl --location 'https://sheetsmcp.googleapis.com/mcp' \
--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_spreadsheet",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

GetContentRequest

JSON 表示法 
{
  "spreadsheetId": string,
  "includeGridData": boolean,
  "fields": [
    string
  ],
  "ranges": [
    string
  ],

  "commentsIncluded": boolean
}
字段
spreadsheetId

string

必需。要请求的电子表格的 ID。
includeGridData

boolean

如果应返回网格数据，则为 True。
fields[]

string

可选。用于指定要返回的 Spreadsheets API 属性的字段掩码，如需详细了解如何使用字段掩码，请参阅 https://developers.google.com/workspace/sheets/api/guides/field-masks。重要提示：请使用基于 Sheets API 响应 JSON 结构的分层路径。- 例如，如需获取工作表的标题和 ID，请使用“sheets.properties.sheetId”和“sheets.properties.title”，而不是“title,sheetId”。- 仅包含您需要的字段。- 如需获取表格，请使用：'sheets.tables' 或 'sheets.properties'。- 如需获取工作表标题和 ID，请使用：'sheets.properties.sheetId' 和 'sheets.properties.title'。
ranges[]

string

可选。要从电子表格中检索的范围的 A1 表示法或 R1C1 表示法。如果未指定，则返回整个电子表格。

联合字段 _comments_included。

_comments_included 只能是下列其中一项：
commentsIncluded

boolean

可选。如果为 true，则回答中将包含注释。默认情况下，不包含注释。

输出架构

表示 JSON 对象。

一种无序的键值对映射，旨在完美捕获 JSON 对象的语义。这样一来，便可将任何任意 JSON 载荷解析为 ProtoJSON 格式的消息字段。

这遵循了 RFC 8259 中关于可互操作 JSON 的准则：值得注意的是，此类型无法表示较大的 Int64 值或 NaN/Infinity 数字，因为 JSON 格式通常不支持其数字类型中的这些值。

如果您不打算将任意 JSON 解析到消息中，则应首选自定义类型的消息，而不是使用此类型。

结构体

JSON 表示法 
{
  "fields": {
    string: value,
    ...
  }
}
字段
fields

map (key: string, value: value (Value format))

无序的动态类型值映射。

包含一系列 "key": value 对的对象。示例：{ "name": "wrench", "mass": "1.3kg", "count": "3" }。

FieldsEntry

JSON 表示法 
{
  "key": string,
  "value": value
}
字段
key

string
value

value (Value format)

值

JSON 表示法 
{

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
字段
联合字段 kind。值的类型。kind 只能是下列其中一项：
nullValue

null

表示 JSON null。
numberValue

number

表示 JSON 数字。不得为 NaN、Infinity 或 -Infinity，因为 JSON 不支持这些值。此外，由于 JSON 格式通常不支持在其数字类型中使用较大的 Int64 值，因此该格式也无法表示这些值。
stringValue

string

表示 JSON 字符串。
boolValue

boolean

表示 JSON 布尔值（JSON 中的 true 或 false 字面量）。
structValue

object (Struct format)

表示 JSON 对象。
listValue

array (ListValue format)

表示 JSON 数组。

ListValue

JSON 表示法 
{
  "values": [
    value
  ]
}
字段
values[]

value (Value format)

动态类型值的重复字段。

NullValue

表示 JSON null。

NullValue 是一个标记，使用只有一个值的枚举来表示 Value 类型联合的 null 值。

如果类型为 NullValue 的字段的值不是 0，则视为无效。大多数 ProtoJSON 序列化程序都会发出一个 Value，并将 null_value 设置为 JSON null，无论整数值是多少，因此会往返于 0 值。

枚举
NULL_VALUE Null 值。

工具注释

工具注释会发送给 MCP 客户端，用于描述指定工具的基本风险。大多数客户端会将这些提示视为不受信任的，但它们可用于确定何时向用户发送确认提示。

除了标题字符串之外，还定义了以下布尔值提示：

  • readOnlyHint：如果为 true，则工具不会修改其环境。默认值：false。
  • destructiveHint：如果为 true，则工具可以执行破坏性操作。如果为 false，则该工具只能执行添加操作。默认值：true。
  • idempotentHint：如果为 true，则使用相同实参重复调用该工具不会对其环境产生任何额外影响。默认值：false。
  • openWorldHint：如果为 true，则工具可以与外部实体的“开放世界”进行交互。如果为 false，则该工具只能与内部实体互动。例如，网络搜索工具是开放世界，而内存工具不是开放世界。

破坏性提示：❌ | 等幂性提示：✅ | 只读提示：✅ | 开放世界提示：✅

授权范围

需要以下 OAuth 范围之一：

  • 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