tableurs

---

title: Spreadsheets sidebar_label: Spreadsheets (7) sidebar_position: 8 doc_type: reference

Spreadsheets

Overview

Read, write, and query your collaborative spreadsheets.

Prerequisites

• API key with the MCP preset and required scopes
• Configured MCP client (see Configuration)

Quick start examples

Read and query a spreadsheet

1. List your spreadsheets :

{
  "name": "spreadsheets_list",
  "arguments": {}
}

2. Read the rows :

{
  "name": "spreadsheets_read_rows",
  "arguments": {
    "spreadsheetId": "uuid-du-tableur",
    "limit": 20
  }
}

3. Query in natural language :

{
  "name": "spreadsheets_query_nl",
  "arguments": {
    "spreadsheetId": "uuid-du-tableur",
    "query": "clients actifs ce mois"
  }
}

---

spreadsheets_delete_rows

[WRITE] Delete rows from a spreadsheet (manual tableurs only).

USE WHEN:

• Need to delete spreadsheet rows programmatically from an MCP client NOTES:
• Source-linked spreadsheets are read-only.
• Soft-deleted spreadsheets (trash) are blocked. RETURNS: rowsDeleted + rowIds deleted.

Scope	mcp.write
Read-only	No
Destructive	Yes
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
rowIds	array	Yes	Row IDs (uuid) to delete (max 500)
sheetId	string (uuid)	Yes	Spreadsheet ID (uuid)
tabId	string (uuid)	No	Optional tab id (uuid) to scope deletions to a tab

Response

Field	Type	Description
success	boolean
rowsDeleted	number
rowIds	array
warnings	array

Related tools : spreadsheets_read_rows, spreadsheets_write_rows, spreadsheets_get_schema

---

spreadsheets_get

[READ] Get spreadsheet metadata (columns, settings, rowCount) and tab list.

USE WHEN:

• Need column IDs / display names before reading rows
• Need to understand sheet structure RETURNS: spreadsheet + tabs summary.

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
sheetId	string (uuid)	Yes	Spreadsheet ID (uuid)

Response

Field	Type	Description
spreadsheet	object
id	string
name	string
description	string
columns	array
settings	unknown
rowCount	number
updatedAt	string
isLocked	boolean
isSourceLinked	boolean
deletedAt	string
tabs	array

Related tools : spreadsheets_list, spreadsheets_get_schema, spreadsheets_read_rows

---

spreadsheets_get_schema

[READ] Get spreadsheet schema (columns) and optional sample rows.

USE WHEN:

• Need column IDs/types before reading/writing rows
• Need a quick preview of data shape RETURNS: columns[] (id/name/displayName/type) + optional sampleRows[].

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
sheetId	string (uuid)	No	Spreadsheet ID (uuid) (default : 0)

Response

Field	Type	Description
spreadsheet	object
id	string
name	string
description	string
rowCount	number
isLocked	boolean
isSourceLinked	boolean
deletedAt	string
columns	array
sampleRows	array

Related tools : spreadsheets_get, spreadsheets_read_rows, spreadsheets_write_rows

---

spreadsheets_list

[DISCOVERY] List spreadsheets (tableurs) in the current workspace.

USE WHEN:

• Need to find a spreadsheet by name
• Need IDs for subsequent spreadsheet tools RETURNS: id, name, rowCount, updatedAt, pinned/source-linked flags.

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
includeTrash	boolean	No	Include soft-deleted spreadsheets (default : false)
limit	number	No	Maximum results to return (default : 50)
offset	number	No	Offset for pagination (default : 0)
search	string	No	Search by spreadsheet name (ILIKE)

Response

Field	Type	Description
spreadsheets	array
id	string
name	string
description	string
rowCount	number
updatedAt	string
isPinned	boolean
isSourceLinked	boolean
deletedAt	string
total	number
hasMore	boolean

Example

{
  "name": "spreadsheets_list",
  "arguments": {}
}

Related tools : spreadsheets_get, spreadsheets_get_schema

---

spreadsheets_query_nl

[READ] Query spreadsheet rows using natural language.

USE WHEN:

• Need to find rows matching business criteria without writing filters
• Query across spreadsheets (or within a specific sheetId) RETURNS: matching rows + an explanation plan (interpreted query, filters, warnings).

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
limit	number	No	Maximum rows to return (default : 50)
query	string	No	Natural language query, e.g. "clients avec CA > 100000"

Response

Field	Type	Description
plan	object
interpretedQuery	string
spreadsheetIds	array
filters	array
warnings	array
confidence	number
isExecutable	boolean
results	array
total	number
hasMore	boolean

Related tools : spreadsheets_list, spreadsheets_read_rows, spreadsheets_get_schema

---

spreadsheets_read_rows

[READ] Read rows from a spreadsheet (optionally filtered by tab).

USE WHEN:

• Need actual row data for analysis
• Need to page through a large spreadsheet RETURNS: rows with rowNumber and raw data (keys are column IDs).

Scope	mcp.read
Read-only	Yes
Destructive	No
Idempotent	Yes

Parameters

Parameter	Type	Required	Description
sheetId	string (uuid)	Yes	Spreadsheet ID (uuid)
cursorRowNumber	number	No	Return rows with row_number > cursorRowNumber (default : 0)
limit	number	No	Maximum rows to return (default : 200)
tabId	string (uuid)	No	Optional tab ID (uuid)

Response

Field	Type	Description
rows	array
nextCursorRowNumber	number
hasMore	boolean

Related tools : spreadsheets_get, spreadsheets_get_schema, spreadsheets_query_nl

---

spreadsheets_write_rows

[WRITE] Insert/update/upsert rows in a spreadsheet (manual tableurs only).

USE WHEN:

• Need to programmatically write spreadsheet data from an MCP client NOTES:
• Source-linked spreadsheets are read-only.
• Soft-deleted spreadsheets (trash) are blocked. RETURNS: rowsAffected + rowIds.

Scope	mcp.write
Read-only	No
Destructive	Yes
Idempotent	No

Parameters

Parameter	Type	Required	Description
data	record	Yes	Row data as { columnId: value }
rowId	string (uuid)	No	Existing row id (uuid) for update/upsert
rowNumber	number	No	Optional row_number to target (upsert by row_number)

Response

Field	Type	Description
success	boolean
operation	enum
rowsAffected	number
rowIds	array
warnings	array

Related tools : spreadsheets_get_schema, spreadsheets_read_rows, spreadsheets_delete_rows

Need help?

Contact us: Support and contact.