Google Sheets Tools

Google Sheets tools let you expose spreadsheet data as MCP tools. Define which sheet to read, which columns to return, and let AI agents filter rows by providing parameter values.

How It Works

1. Connect a Google Sheets source by providing the spreadsheet ID
2. Create a tool with tool_type: gsheet
3. Configure the sheet name, header row, columns, and row limits
4. Add parameters that map to column names for filtering

When an AI agent calls the tool, Datatape reads the sheet, applies filters based on the provided parameters, and returns matching rows.

Configuration

Sheet Name

The exact name of the worksheet tab to read from (e.g., "Sheet1", "Q4 Revenue", "Employee Directory"). This is case-sensitive.

Header Row

The row number that contains column headers (default: 1). Data is read starting from the row after the header. Set this to 2 or higher if your sheet has title rows or notes above the actual headers.

Return Columns

An optional list of column names to include in the response. When set, only these columns are returned. When omitted, all columns are included.

["name", "email", "department", "start_date"]

This is useful for sheets with many columns where the AI agent only needs a subset.

Max Rows

The maximum number of rows to return (default: 500). This prevents large sheets from overwhelming AI agent context windows.

Filtering

Parameters define the filter criteria. Each parameter name should match a column header in the sheet. When an agent provides a value, Datatape filters rows where that column matches exactly (case-insensitive).

Multiple parameters use AND logic — all conditions must match.

Example: Employee Directory

Sheet: "Employees" with columns: Name, Email, Department, Location, Start Date

Tool configuration:

• Sheet name: Employees
• Header row: 1
• Return columns: ["Name", "Email", "Department", "Location"]
• Max rows: 100
• Parameters:
  • Department (string, optional) — Filter by department name
  • Location (string, optional) — Filter by office location

An agent calling with {"Department": "Sales"} receives all Sales employees, limited to 100 rows, with only the four specified columns.

Preview Mode

The preview endpoint shows the sheet name and which filter columns will be applied, without reading the actual spreadsheet data.

{
  "sheet_name": "Employees",
  "filter_columns": ["Department"]
}

Limitations

• Filtering is exact match only (case-insensitive)
• No support for range filters, partial matches, or regex
• The entire sheet is read into memory before filtering, so very large sheets (100K+ rows) may be slow
• Google Sheets API rate limits apply (100 requests per 100 seconds per user)