xlsx-mcp-server
Advanced tools
MCP server for XLSX spreadsheet editing — read, write, format, and manage Excel workbooks
A local MCP server for reading and editing Excel (.xlsx) files. Works with Claude Code, Cursor, and any MCP-compatible client.
37 tools for cell data, formatting, formulas, sheet management, row/column operations, data validation, named ranges, and cell merging — all running locally via stdio with no file uploads.
| Category | Tools |
|---|---|
| Read | get_workbook_info, read_sheet, read_cell, search_cells, get_sheet_properties, list_named_ranges, list_data_validations, list_images |
| Write | write_cell, write_cells, write_row, write_rows, clear_cells, create_workbook |
| Format | format_cells, format_cells_bulk |
| Rows & columns | set_column_width, set_column_widths, set_row_height, set_row_heights, insert_rows, delete_rows, insert_columns, delete_columns |
| Sheet ops | add_sheet, rename_sheet, delete_sheet, copy_sheet |
| View | set_freeze_panes, set_auto_filter, remove_auto_filter |
| Validation | add_data_validation, remove_data_validation |
| Structure | add_named_range, delete_named_range, merge_cells, unmerge_cells |
The writing, formatting, and row/column tools have bulk variants (write_cells, write_rows, format_cells_bulk, set_column_widths, set_row_heights) that process multiple targets in a single file read/write cycle. Use these instead of calling the single-target versions in a loop.
Write formulas by prefixing the value with =:
write_cell → value: "=SUM(A1:A10)"
write_cells → cells: [{cell: "B1", value: "=A1*2"}, {cell: "B2", value: "=VLOOKUP(...)"}]
read_cell returns both the formula and the cached result.
npm install -g xlsx-mcp-server
Then add to your MCP config (see Configuration below).
Just add the config — npx downloads and runs it automatically:
{
"mcpServers": {
"xlsx-editor": {
"command": "npx",
"args": ["-y", "xlsx-mcp-server"]
}
}
}
git clone https://github.com/knorq-ai/xlsx-mcp-server.git
cd xlsx-mcp-server
npm install
npm run build
npm link # makes `xlsx-mcp-server` available globally
Add to your project's .mcp.json (per-project) or ~/.claude/settings.json (global):
{
"mcpServers": {
"xlsx-editor": {
"command": "npx",
"args": ["-y", "xlsx-mcp-server"]
}
}
}
Add to your MCP server configuration in Cursor settings:
{
"mcpServers": {
"xlsx-editor": {
"command": "npx",
"args": ["-y", "xlsx-mcp-server"]
}
}
}
If you built from source and ran npm link:
{
"mcpServers": {
"xlsx-editor": {
"command": "xlsx-mcp-server"
}
}
}
Or reference the built file directly:
{
"mcpServers": {
"xlsx-editor": {
"command": "node",
"args": ["/absolute/path/to/xlsx-mcp-server/dist/index.js"]
}
}
}
npm publish
Recipients install with:
npm install -g xlsx-mcp-server
Or skip the install entirely — just share the .mcp.json config with the npx setup above and it works out of the box.
Share the repository. Recipients run:
git clone https://github.com/knorq-ai/xlsx-mcp-server.git
cd xlsx-mcp-server
npm install
npm run build
npm link
Then add the config above.
get_workbook_info — Sheet list, named range count, file properties.
file_path
read_sheet — Read cell data from a sheet with optional range.
file_path, sheet, range?
read_cell — Single cell's value, formula, type, and formatting.
file_path, sheet, cell
search_cells — Search for text or numbers across cells.
file_path, query, sheet?, case_sensitive?
get_sheet_properties — Sheet state, dimensions, freeze panes, auto filter, tab color.
file_path, sheet
list_named_ranges — List all named ranges with names and references.
file_path
list_data_validations — List data validation rules on a sheet.
file_path, sheet
list_images — List embedded images with names, extensions, and dimensions.
file_path, sheet
write_cell — Set a cell's value or formula. Prefix with = for formulas.
file_path, sheet, cell, value
write_cells — Set multiple cells at once.
file_path, sheet, cells (array of {cell, value})
write_row — Write a row of values starting from a position.
file_path, sheet, row, values, start_column?
write_rows — Write multiple rows of data at once.
file_path, sheet, start_row, rows (2D array), start_column?
clear_cells — Clear values in a range (keeps formatting).
file_path, sheet, range
create_workbook — Create a new empty .xlsx workbook.
file_path, sheet_name?
format_cells — Apply formatting to a cell range: font (bold, italic, underline, strikethrough, name, size, color), fill (color, pattern), borders (style, color, sides), alignment (horizontal, vertical, wrap, rotation), number format.
file_path, sheet, range, format
format_cells_bulk — Apply different formatting to multiple ranges at once. Single file read/write cycle.
file_path, sheet, groups (array of {range, format})
set_column_width — Set the width of a column (in characters).
file_path, sheet, column, width
set_column_widths — Set widths for multiple columns at once.
file_path, sheet, columns (array of {column, width})
set_row_height — Set the height of a row (in points).
file_path, sheet, row, height
set_row_heights — Set heights for multiple rows at once.
file_path, sheet, rows (array of {row, height})
insert_rows — Insert empty rows at a position.
file_path, sheet, row, count
delete_rows — Delete rows at a position.
file_path, sheet, row, count
insert_columns — Insert empty columns at a position.
file_path, sheet, column, count
delete_columns — Delete columns at a position.
file_path, sheet, column, count
add_sheet — Add a new empty sheet.
file_path, name
rename_sheet — Rename an existing sheet.
file_path, sheet, new_name
delete_sheet — Delete a sheet from the workbook.
file_path, sheet
copy_sheet — Copy a sheet within the workbook.
file_path, source_sheet, new_name
set_freeze_panes — Freeze rows and/or columns. Pass 0 to unfreeze.
file_path, sheet, row, column
set_auto_filter — Enable auto filter on a range.
file_path, sheet, range
remove_auto_filter — Remove auto filter from a sheet.
file_path, sheet
add_data_validation — Add a validation rule (list, whole, decimal, date, textLength, custom) with operator, messages, and prompts.
file_path, sheet, range, type, formulae, operator?, allow_blank?, show_error_message?, error_title?, error?, show_input_message?, prompt_title?, prompt?
remove_data_validation — Remove validation rules from a range.
file_path, sheet, range
add_named_range — Add a named range (workbook-scoped or sheet-scoped).
file_path, name, range, sheet?
delete_named_range — Delete a named range.
file_path, name
merge_cells — Merge a range of cells.
file_path, sheet, range
unmerge_cells — Unmerge a previously merged range.
file_path, sheet, range
| Feature | Detail |
|---|---|
| Formula recalculation | Cached results are read, but formulas are NOT recalculated when values change. Open the file in Excel to recalculate. |
| Charts | Cannot read, create, or modify charts. Existing charts are preserved on save. |
| Pivot tables | Cannot read or create pivot tables |
| Conditional formatting | Cannot read or create conditional formatting rules |
| VBA/macros | Macro-enabled workbooks (.xlsm) are not supported |
| Formula ref auto-update | Inserting/deleting rows or columns does NOT shift cell references in existing formulas (e.g. =SUM(A1:A10) stays unchanged after row insert) |
AI agents can manipulate Excel via raw Python (openpyxl), but MCP tools are significantly more token-efficient:
| Metric | MCP tools | Raw Python |
|---|---|---|
| Output tokens per operation | 60–85% less | Baseline (agent must generate full code) |
| Cost per operation | 50–80% less | Baseline |
| Break-even | 2 operations | — |
| Debug iterations | None (validated inputs) | ~1.5 retries/task on average |
The savings come primarily from eliminating code generation — output tokens cost 5× more than input tokens. MCP tool calls are small structured parameters (~30–50 tokens), while equivalent Python code requires ~80–200 output tokens per operation (imports, style objects, iteration, save).
Formatting operations see the largest savings (~75%) because openpyxl's styling API (PatternFill, Border, Side, Font) is particularly verbose. Simple cell read/write sees smaller but still meaningful savings (~60%).
See docs/token-efficiency-analysis.md for detailed scenario breakdowns.
MIT
FAQs
MCP server for XLSX spreadsheet editing — read, write, format, and manage Excel workbooks
We found that xlsx-mcp-server demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Product
Socket MCP now lets AI assistants review org alerts, investigate threats using the Socket threat feed, and inspect package files in addition to dependency scoring.
Product
Socket Firewall blocks malicious VS Code and Open VSX extensions before install, protecting developers from compromised editor marketplaces.
Research
More than 140 Mastra npm packages were compromised in a supply chain attack that used a typosquatted dependency to deliver a cross-platform infostealer during installation.