How to Read Excel Files with Specific Ranges Using Desktop Commander MCP

Use the read_file tool with sheet, range, offset, and length options in the ReadOptions interface to extract precise cell ranges from Excel workbooks.

Desktop Commander MCP provides native Excel support through the ExcelFileHandler (src/utils/files/excel.ts), treating spreadsheets as first-class data sources. When you need to read Excel files with specific ranges, the handler interprets additional options defined in the ReadOptions interface (src/utils/files/base.ts).

Available Range Options

The ReadOptions object accepts four parameters for precise Excel data extraction:

Option	Type	Purpose
sheet	string | number	Target worksheet by name ("Sheet1") or 0-based index (0). Defaults to first sheet if omitted.
range	string	Cell range in A1 notation, e.g. A1:C10. Supports sheet prefix: "Sheet1!A1:C10".
offset	number	Row offset for pagination. Positive values skip rows; negative values return trailing rows.
length	number	Maximum rows to return after offset. Falls back to fileReadLineLimit (default 1000) if omitted.

How the Excel Handler Processes Ranges

The worksheetToArray function in src/utils/files/excel.ts executes a three-stage workflow:

1. Worksheet selection — resolves the target sheet from explicit sheet argument, numeric index, or sheet name parsed from a prefixed range.
2. Range parsing — parseCellRange converts A1-style addresses into numeric start/end row and column boundaries.
3. Pagination application — adjusts row boundaries based on offset and length parameters.

Offset Behavior Details

• offset > 0: Adds to start row (startRow = startRow + offset)
• offset < 0: Returns the last N rows (mirrors text file pagination behavior)

Practical Code Examples

Read a specific cell range from the first sheet

{
  "tool": "read_file",
  "arguments": {
    "path": "data/sales_report.xlsx",
    "range": "B2:F25"
  }
}

Read from a named sheet with explicit range

{
  "tool": "read_file",
  "arguments": {
    "path": "data/sales_report.xlsx",
    "sheet": "Q2_Revenue",
    "range": "A1:D100"
  }
}

Combined sheet and range in single string

{
  "tool": "read_file",
  "arguments": {
    "path": "data/sales_report.xlsx",
    "range": "Q2_Revenue!A1:D100"
  }
}

Paginated extraction with offset and length

{
  "tool": "read_file",
  "arguments": {
    "path": "data/sales_report.xlsx",
    "sheet": "Transactions",
    "range": "A1:Z5000",
    "offset": 100,
    "length": 50
  }
}

This returns rows 101-150 from the specified range (skips first 100, then takes 50).

Extract trailing rows with negative offset

{
  "tool": "read_file",
  "arguments": {
    "path": "data/sales_report.xlsx",
    "range": "A1:C1000",
    "offset": -20
  }
}

Returns the last 20 rows of the specified range.

Configuration Limits

According to the Desktop Commander MCP source code, the length parameter defaults to the server-side fileReadLineLimit setting. The default is 1000 rows. Configure this limit in your MCP server settings if you need larger extractions.

Summary

• Desktop Commander MCP reads Excel files through ExcelFileHandler in src/utils/files/excel.ts
• Use range for A1-style cell selection; prefix with sheet name or use separate sheet parameter
• Combine offset and length for server-side pagination of large datasets
• Negative offset values return trailing rows, matching text file behavior
• Default row limit is 1000; override with explicit length or server configuration

Frequently Asked Questions

Can I reference sheets by index instead of name?

Yes. Pass a 0-based number to the sheet option: "sheet": 2 selects the third worksheet. This is implemented in the worksheet selection logic of worksheetToArray in src/utils/files/excel.ts.

Does range selection work with merged cells?

The parseCellRange function operates on A1-style addresses and returns numeric boundaries. Merged cells are read according to the underlying sheet data structure—no special handling is applied by the handler.

What happens if my range exceeds available data?

The handler extracts up to the boundary of actual populated cells. Empty cells within the range return as null or empty string values depending on the cell type. The length parameter caps results regardless of range size.

Can I use these options with CSV files?

No. The sheet and range options are Excel-specific and processed only by ExcelFileHandler. CSV files use the base text handler, which supports offset and length but not cell-range addressing.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}