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

> Learn to read specific Excel ranges with Desktop Commander MCP. Use read_file tool with sheet, range, offset, and length options for precise data extraction.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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

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

```

### Read from a named sheet with explicit range

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

```

### Combined sheet and range in single string

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

```

### Paginated extraction with offset and length

```javascript
{
  "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

```javascript
{
  "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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/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.