MCP Tools Reference: sheetsmcp.googleapis.com

Ferramenta: get_spreadsheet

Retorna o conteúdo da planilha especificada. Retorna títulos, nomes de páginas, propriedades de grade e outros metadados para o ID da planilha fornecido. Também retorna dados de grade completos, se solicitado.

Corresponde a spreadsheets.get na API REST: https://developers.google.com/workspace/sheets/api/reference/rest/v4/spreadsheets/get

Esquema: - spreadsheet_id (string, obrigatório): o ID da planilha a ser solicitada. - include_grid_data (booleano, opcional): verdadeiro se os dados da grade precisarem ser retornados. O padrão é "falso". - fields (matriz de strings, opcional): máscaras de campo que especificam quais propriedades retornar (por exemplo, ["sheets.properties.sheetId", "sheets.properties.title"]). - comments_included (booleano, opcional): se for verdadeiro, os comentários serão incluídos na resposta. O padrão é "falso". - ranges (matriz de strings, opcional): os intervalos A1 ou R1C1 a serem recuperados da planilha. Se não for especificada, a planilha inteira será retornada.

O exemplo de código abaixo mostra como usar curl para chamar a ferramenta MCP get_spreadsheet.

Solicitação curl 
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_spreadsheet",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Esquema de entrada

GetContentRequest

Representação JSON 
{
  "spreadsheetId": string,
  "includeGridData": boolean,
  "fields": [
    string
  ],
  "ranges": [
    string
  ],

  "commentsIncluded": boolean
}
Campos
spreadsheetId

string

Obrigatório. O ID da planilha a ser solicitada.
includeGridData

boolean

Verdadeiro se os dados da grade precisarem ser retornados.
fields[]

string

Opcional. Uma máscara de campo para especificar quais propriedades da API Spreadsheets serão retornadas. Consulte https://developers.google.com/workspace/sheets/api/guides/field-masks para saber mais sobre como usar as máscaras de campo. IMPORTANTE: use caminhos hierárquicos com base na estrutura JSON de resposta da API Sheets. - Por exemplo, para receber o título e o ID da página, use "sheets.properties.sheetId" e "sheets.properties.title" em vez de "title,sheetId". - Inclua apenas os campos necessários. - Para acessar tabelas, use: "sheets.tables" ou "sheets.properties". - Para receber os títulos e IDs das páginas, use: "sheets.properties.sheetId" e "sheets.properties.title".
ranges[]

string

Opcional. A notação A1 ou R1C1 dos intervalos a serem recuperados da planilha. Se não for especificado, a planilha inteira será retornada.

Campo de união _comments_included.

_comments_included pode ser apenas de um dos tipos a seguir:
commentsIncluded

boolean

Opcional. Se for verdadeiro, os comentários serão incluídos na resposta. Por padrão, os comentários não são incluídos.

Esquema de saída

GetContentResponse

Representação JSON 
{
  "content": {
    object
  }
}
Campos
content

object (Struct format)

A planilha, no formato JSON do recurso Spreadsheet da API Sheets.

Struct

Representação JSON 
{
  "fields": {
    string: value,
    ...
  }
}
Campos
fields

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

Mapa não ordenado de valores digitados dinamicamente.

Um objeto com uma lista de pares "key": value. Exemplo: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

Representação JSON 
{
  "key": string,
  "value": value
}
Campos
key

string
value

value (Value format)

Valor

Representação JSON 
{

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
Campos
Campo de união kind. O tipo de valor. kind pode ser apenas de um dos tipos a seguir:
nullValue

null

Representa um null JSON.
numberValue

number

Representa um número JSON. Não pode ser NaN, Infinity ou -Infinity, porque eles não são compatíveis com JSON. Isso também não pode representar valores Int64 grandes, já que o formato JSON geralmente não os aceita no tipo de número.
stringValue

string

Representa uma string JSON.
boolValue

boolean

Representa um booleano JSON (literal true ou false em JSON).
structValue

object (Struct format)

Representa um objeto JSON.
listValue

array (ListValue format)

Representa uma matriz JSON.

ListValue

Representação JSON 
{
  "values": [
    value
  ]
}
Campos
values[]

value (Value format)

Campo repetido de valores digitados dinamicamente.

NullValue

Representa um null JSON.

NullValue é um sentinela, que usa um tipo enumerado com apenas um valor para representar o valor nulo da união de tipos Value.

Um campo do tipo NullValue com qualquer valor diferente de 0 é considerado inválido. A maioria dos serializadores ProtoJSON emite um Value com um null_value definido como um null JSON, independentemente do valor inteiro, e, portanto, faz uma ida e volta para um valor 0.

Tipos enumerados
NULL_VALUE Valor nulo.

Anotações de ferramentas

As anotações de ferramentas são enviadas aos clientes do MCP para descrever o risco básico de uma determinada ferramenta. A maioria dos clientes trata essas dicas como não confiáveis, mas elas podem ser usadas para decidir quando um pedido de confirmação pode ser enviado a um usuário.

Além da string de título, as seguintes dicas booleanas são definidas:

  • readOnlyHint: se for verdadeiro, a ferramenta não modifica o ambiente. (Padrão: falso).
  • destructiveHint: se for verdadeiro, a ferramenta poderá realizar ações destrutivas. Se for falso, a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
  • idempotentHint: se for verdadeiro, chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente. (Padrão: falso).
  • openWorldHint: se for verdadeiro, a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for falso, a ferramenta só poderá interagir com entidades internas. Por exemplo, uma ferramenta de pesquisa na Web seria de mundo aberto, enquanto uma ferramenta de memória não seria.

Dica destrutiva: ❌ | Dica idempotente: ✅ | Dica somente leitura: ✅ | Dica de mundo aberto: ✅

Escopos de autorização

Requer um dos seguintes escopos do 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