read_range
Extract specific cell data from spreadsheet files by defining a rectangular range. Returns values as a structured 2D array with empty cells as null.
Instructions
Read a rectangular range of cells as a list of rows.
Returns a 2D array where each inner list is one row of values. Empty cells return null.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| file | Yes | Path to the spreadsheet file | |
| range_str | Yes | Cell range in A1 notation, e.g. 'A1:D10' or '$A$1:$D$10' | |
| sheet | No | Sheet name. Defaults to the first sheet if omitted. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- Implementation of the 'read_range' tool handler, which uses the mcp.tool decorator and interacts with openpyxl to read a spreadsheet range.
@mcp.tool() def read_range( file: Annotated[str, Field(description="Path to the spreadsheet file")], range_str: Annotated[str, Field(description="Cell range in A1 notation, e.g. 'A1:D10' or '$A$1:$D$10'")], sheet: Annotated[str | None, Field(description="Sheet name. Defaults to the first sheet if omitted.")] = None, ) -> list[list]: """Read a rectangular range of cells as a list of rows. Returns a 2D array where each inner list is one row of values. Empty cells return null. """ wb = load_workbook(file) ws = _resolve_sheet(wb, sheet) min_col, min_row, max_col, max_row = parse_range(range_str) rows = ws.iter_rows( min_row=min_row, max_row=max_row, min_col=min_col, max_col=max_col, ) return [list(r) for r in rows]