MCP Tools Reference: sheetsmcp.googleapis.com

工具：update_values

在試算表範圍中設定值。對應於 REST API 中的 spreadsheets.values.update：https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets.values/update

下列範例示範如何使用 curl 叫用 update_values 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": "update_values",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

輸入內容的結構定義

UpdateValuesRequest

JSON 表示法 
{
  "spreadsheetId": string,
  "range": string,
  "values": [
    array
  ]
}
欄位
spreadsheetId

string

必填。要更新的試算表 ID。
range

string

必填。要更新的值的 A1 標記。
values[]

array (ListValue format)

必填。讀取或要寫入的資料。這是陣列的陣列，外層陣列代表所有資料，每個內層陣列代表一列。內部陣列中的每個項目都對應一個儲存格。支援的值類型包括：bool、string 和 double。系統會略過空值。如要將儲存格設為空值，請將字串值設為空字串。

ListValue

JSON 表示法 
{
  "values": [
    value
  ]
}
欄位
values[]

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 陣列。

結構

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)

NullValue

代表 JSON null。

NullValue 是哨兵，使用只有一個值的列舉，代表 Value 型別聯集的空值。

如果 NullValue 類型的欄位值不是 0，則視為無效。大多數 ProtoJSON 序列化程式都會發出 Value，並將 null_value 設為 JSON null (不論整數值為何)，因此會來回傳輸至 0 值。

列舉
NULL_VALUE 空值。

輸出內容的結構定義

代表 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 型別聯集的空值。

如果 NullValue 類型的欄位值不是 0，則視為無效。大多數 ProtoJSON 序列化程式都會發出 Value，並將 null_value 設為 JSON null (不論整數值為何)，因此會來回傳輸至 0 值。

列舉
NULL_VALUE 空值。

工具註解

破壞性提示：❌ | 等冪提示：❌ | 唯讀提示：❌ | 開放世界提示：✅

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/drive.file
  • https://www.googleapis.com/auth/spreadsheets