Local MCP

Excel Read

excel_read

Read-only

Reads data from an Excel spreadsheet (.xlsx file). Returns the first row as headers and the remaining data rows as rows — mirroring excel_create's headers/rows params, so a read→create round-trip needs no manual row-0 handling.

Input Schema

Name	Required	Description
`path`	Yes	Absolute path to the .xlsx file
`max_rows`	No	Max DATA rows to return, not counting the header row, which always comes back as `headers` (default 100)
`sheet_name`	No	Sheet name to read (optional, reads first sheet). Matched without case. A name that no sheet has is an error listing the available ones — it never falls back to the first sheet.
`force_download`	No	If the file is stored in the cloud and evicted from this Mac (dataless), request the download and wait for it instead of failing. Off by default: a download can take minutes and use metered data, so it is the caller's decision.

Output Schema

Name	Required	Description
`rows`	Yes	Data rows AFTER the header row; numeric cells are numbers, boolean cells are booleans and text cells are strings — feeds straight into excel_create's `rows`. Empty cells at the end of a row are left out.
`count`	Yes	Number of DATA rows returned (excludes the header row)
`sheet`	Yes	Name of the sheet that was read
`sheets`	Yes	All sheet names in the workbook
`headers`	Yes	The first row, as column headers — mirrors excel_create's `headers` param
`sparse_cells`	No	Present only when the sheet has cells far outside the table (beyond column 64): each is {row, col, value} with REAL 1-based indices. Kept out of `rows` so one stray cell can't pad every row — but never dropped.
`formulas_note`	No	Present when some cells hold a formula with no computed value yet

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 24, 2026

addedOutput schema / properties / formulas_note

Added value: +{
+  "description": "Present when some cells hold a formula with no computed value yet",
+  "enum": [
+    "These cells hold a formula with no computed value yet, so they show the formula text (e.g. =SUM(B2:B3)), not a result. Excel or Numbers compute it when the file is opened and saved."
+  ],
+  "type": "string"
+}

Changed2 schema fields changedOct 22, 2026

changedInput schema / properties / max_rows / description

Previous value: -"Max rows to return (default 100)"New value: +"Max DATA rows to return, not counting the header row, which always comes back as `headers` (default 100)"

changedOutput schema / properties / rows / description

Previous value: -"Data rows AFTER the header row; numeric cells are numbers and text cells are strings — feeds straight into excel_create's `rows`"New value: +"Data rows AFTER the header row; numeric cells are numbers, boolean cells are booleans and text cells are strings — feeds straight into excel_create's `rows`. Empty cells at the end of a row are left out."

Changed1 schema field changedSep 30, 2026

changedInput schema / properties / sheet_name / description

Previous value: -"Sheet name to read (optional, reads first sheet)"New value: +"Sheet name to read (optional, reads first sheet). Matched without case. A name that no sheet has is an error listing the available ones — it never falls back to the first sheet."

Changed1 schema field changedSep 29, 2026

changedInput schema / properties / sheet_name / description

Previous value: -"Sheet name to read (optional, reads first sheet). Matched without case. A name that no sheet has is an error listing the available ones — it never falls back to the first sheet."New value: +"Sheet name to read (optional, reads first sheet)"

Changed1 schema field changedSep 21, 2026

changedInput schema / properties / sheet_name / description

Previous value: -"Sheet name to read (optional, reads first sheet)"New value: +"Sheet name to read (optional, reads first sheet). Matched without case. A name that no sheet has is an error listing the available ones — it never falls back to the first sheet."

Changed1 schema field changedSep 8, 2026

addedInput schema / properties / force_download

Added value: +{
+  "description": "If the file is stored in the cloud and evicted from this Mac (dataless), request the download and wait for it instead of failing. Off by default: a download can take minutes and use metered data, so it is the caller's decision.",
+  "type": "boolean"
+}

Changed2 schema fields changedSep 8, 2026

changedOutput schema / properties / rows / description

Previous value: -"Data rows AFTER the header row (each an array of cell-value strings) — feeds straight into excel_create's `rows`"New value: +"Data rows AFTER the header row; numeric cells are numbers and text cells are strings — feeds straight into excel_create's `rows`"

removedOutput schema / properties / rows / items / items / type
```
Removed value: -"string"
```

Changed1 schema field changedAug 5, 2026

addedOutput schema / properties / sparse_cells

Added value: +{
+  "description": "Present only when the sheet has cells far outside the table (beyond column 64): each is {row, col, value} with REAL 1-based indices. Kept out of `rows` so one stray cell can't pad every row — but never dropped.",
+  "items": {
+    "type": "object"
+  },
+  "type": "array"
+}

Changed4 schema fields changedJul 30, 2026

changedOutput schema / properties / count / description

Previous value: -"Number of rows returned"New value: +"Number of DATA rows returned (excludes the header row)"

addedOutput schema / properties / headers

Added value: +{
+  "description": "The first row, as column headers — mirrors excel_create's `headers` param",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}

changedOutput schema / properties / rows / description

Previous value: -"Row data as arrays of cell-value strings"New value: +"Data rows AFTER the header row (each an array of cell-value strings) — feeds straight into excel_create's `rows`"

changedOutput schema / required

Previous value: -[
-  "sheet",
-  "sheets",
-  "rows",
-  "count"
-]New value: +[
+  "sheet",
+  "sheets",
+  "headers",
+  "rows",
+  "count"
+]

First observedJun 30, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnlyHint, destructiveHint=false, and openWorldHint=false. The description adds useful behavioral detail by explaining the returned headers/rows layout and the round-trip alignment with excel_create, which is meaningful beyond the structured annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tightly written sentences with the core behavior front-loaded and zero redundant text. The round-trip note earns its place by adding practical context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is complete for a read tool whose annotations cover safety and whose schema covers all parameters. Even though an output schema exists, the description helpfully summarizes the return shape without becoming verbose.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents path, max_rows, sheet_name, and force_download thoroughly. The description does not add input-parameter semantics beyond noting the header/data-row output mapping, so the baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Reads data from an Excel spreadsheet') and distinguishes the operation from sibling spreadsheet tools like excel_create and excel_write_cell. It also clarifies the returned structure, so an agent knows exactly what this tool produces.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives clear context by explaining the read→create round-trip relationship with excel_create, which helps an agent understand the tool's role. It does not explicitly state when not to use it, but there is no competing Excel-read sibling, so the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All Local MCP tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

Excel Read

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources