This post was generated by an AI agent from an article the account owner published in Japanese on note. The wording is not human-written.
A client sent over an Excel specification file in one project with a simple ask: take a look and confirm the details. Claude Code's Read tool, pointed at the .xlsx file, returned a flat answer:
This tool cannot read binary files.
It could not read it. The same tool handles PDFs fine. It handles images fine. Excel was the one format it rejected outright.
The workaround, before the fix described below, was a Python script built around openpyxl to pull cell values out manually:
import openpyxl
wb = openpyxl.load_workbook('仕様書.xlsx')
ws = wb.active
for row in ws.iter_rows(values_only=True):
print(row)
That covered plain cell data, but it fell apart for a common pattern: specs written inside shapes or text boxes embedded in the sheet rather than in cells. Handling that meant unzipping the .xlsx file as an archive, parsing the XML inside it, and extracting images separately. Doing that for every incoming spec file was not sustainable.
Why Claude Code can't read Excel by default
Claude Code's Read tool supports text files, images, and PDFs. An .xlsx file is a binary format (technically a zip archive of XML), so it falls outside what Read can parse directly. There is no built-in path from Claude Code to Excel content.
The fix: Excel MCP Server
MCP (Model Context Protocol) servers extend Claude Code with external tool capabilities, similar to a plugin. In this case, the server adopted was negokaz/excel-mcp-server, built by a Japanese developer, which is noted as a safe choice specifically for handling Excel files in Japanese.
Setup is two steps.
First, open Claude Code's configuration file (.claude.json in the home directory) and add an entry under mcpServers:
{
"excel": {
"command": "cmd",
"args": ["/c", "npx", "--yes", "@negokaz/excel-mcp-server"],
"env": {
"EXCEL_MCP_PAGING_CELLS_LIMIT": "4000"
},
"type": "stdio"
}
}
On Mac or Linux, command should be npx instead of cmd, and args should be ["--yes", "@negokaz/excel-mcp-server"].
Second, save the config and restart Claude Code. That's the entire setup.
The one catch: Node.js version
After the first restart, the server did not start. The error pointed to an outdated Node.js installation. The MCP server requires Node.js 20.x or higher; anyone still on the 18.x line needs to upgrade Node first, or the setup looks broken when the real issue is just the Node version.
Verifying it worked
Once Node.js was updated and Claude Code restarted again, the same client Excel file that had previously failed was handed back to Claude Code with a plain "read this Excel file" request. This time it worked: cell data came through, along with sheet information and cell styling. The server also read images and comments embedded in the spreadsheet and incorporated their content into the response.
Work that previously required a custom Python extraction pipeline was reduced to a single natural-language request.
What it could actually do
- Read Excel cell data directly
- Recognize and interpret embedded images
- Read comments attached to cells
- Parse overall sheet structure
- Handle Japanese-language content without issue
Compared to the earlier Python-based conversion approach, the reported time spent on this task dropped by roughly a factor of ten.
Takeaways
- Claude Code cannot read Excel files out of the box
- Installing
negokaz/excel-mcp-serveradds direct Excel reading support - Setup is a few lines added to
.claude.jsonplus a restart - Node.js 20.x or higher is required; this is the most likely source of setup failures
- The server also reads and interprets embedded images and comments, not just cell values
Follow @kmrb_works here on DEV for more field notes from real development work. Also on X and note, mostly in Japanese.
Top comments (0)