Excel MCP Server

A Model Context Protocol (MCP) server that reads and writes MS Excel data.

Why Fork?

This fork (pcvelz/excel-mcp-server) adds features needed for real-world bookkeeping workflows that are not yet available upstream:

Alignment support in excel_format_range — set horizontal/vertical alignment (e.g., left-align numbers)
Alignment in showStyle output — read back cell alignment when using showStyle: true
Cell type attributes — type attribute (string, number, formula, date) in showStyle output
Raw value attributes — raw attribute showing unformatted values alongside displayed values
ISO date auto-conversion — write ISO date strings (e.g., "2026-02-03") and they're automatically converted to Excel date serial numbers
Sheet management — excel_rename_sheet, excel_delete_sheet and excel_move_sheet for renaming, removing and reordering tabs
New workbooks from scratch — excel_write_to_sheet with newSheet: true creates the file when the path does not exist yet
Row management - excel_delete_rows and excel_insert_rows, with formulas adjusted the way Excel adjusts them (#REF! for references into deleted rows)
Merges, column widths, conditional formatting and data validation in showStyle output — reported alongside the styled cell table
Conditional formatting, read and write — showStyle reports every rule with its formula, its background colour and the priority Excel resolves overlaps by; excel_conditional_format writes and clears rules

See the upstream comparison for full diff.

Features

Read/Write text values
Read/Write formulas
Create new sheets and new workbooks
Rename, delete and reorder sheets

🪟Windows only:

Live editing
Capture screen image from a sheet

For more details, see the tools section.

Requirements

Node.js 20.x or later

Supported file formats

xlsx (Excel book)
xlsm (Excel macro-enabled book)
xltx (Excel template)
xltm (Excel macro-enabled template)

Installation

Installing via NPM

excel-mcp-server is automatically installed by adding the following configuration to the MCP servers configuration.

For Windows:

{
    "mcpServers": {
        "excel": {
            "command": "cmd",
            "args": ["/c", "npx", "--yes", "excel-mcp-server-pcvelz"],
            "env": {
                "EXCEL_MCP_PAGING_CELLS_LIMIT": "4000"
            }
        }
    }
}

For other platforms:

{
    "mcpServers": {
        "excel": {
            "command": "npx",
            "args": ["--yes", "excel-mcp-server-pcvelz"],
            "env": {
                "EXCEL_MCP_PAGING_CELLS_LIMIT": "4000"
            }
        }
    }
}

Installing via Smithery

To install Excel MCP Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install excel-mcp-server-pcvelz --client claude

Tools

`excel_describe_sheets`

List all sheet information of specified Excel file.

Arguments:

fileAbsolutePath
- Absolute path to the Excel file

`excel_read_sheet`

Read values from Excel sheet with pagination.

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Sheet name in the Excel file
range
- Range of cells to read in the Excel sheet (e.g., "A1:C10"). [default: first paging range]
showFormula
- Show formula instead of value [default: false]
showStyle
- Show style information for cells [default: false]
- When enabled, output includes:
  - style-ref: References to style definitions (border, font, fill, alignment, numFmt)
  - type: Cell type (number, string, date, bool, formula, error)
  - raw: Raw/unformatted value (shown when different from displayed value, e.g., raw="45691" for a date displayed as "3-Feb")
  - merged cells and column widths in the metadata list, since these live on the sheet rather than on individual cells

`excel_screen_capture`

[Windows only] Take a screenshot of the Excel sheet with pagination.

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Sheet name in the Excel file
range
- Range of cells to read in the Excel sheet (e.g., "A1:C10"). [default: first paging range]

`excel_write_to_sheet`

Write values to the Excel sheet.

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Sheet name in the Excel file
newSheet (optional, default: false)
- Create a new sheet if true, otherwise write to the existing sheet
- If the file itself does not exist yet, a new workbook is created containing just that sheet
range
- Range of cells to read in the Excel sheet (e.g., "A1:C10").
values
- Values to write to the Excel sheet. If the value is a formula, it should start with "="
- ISO date strings (e.g., "2026-02-03", "2026-02-03T10:30:00", "2026-02-03T10:30:00Z") are automatically converted to Excel date serial numbers

`excel_create_table`

Create a table in the Excel sheet

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Sheet name where the table is created
range
- Range to be a table (e.g., "A1:C10")
tableName
- Table name to be created

`excel_copy_sheet`

Copy existing sheet to a new sheet

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
srcSheetName
- Source sheet name in the Excel file
dstSheetName
- Sheet name to be copied

`excel_rename_sheet`

Rename a sheet. Cell values, formatting, merged cells, column widths and row heights are preserved, and everything that names the sheet follows the rename: formulas (including 3D references such as Sheet1:Sheet3!A1), defined names, data validation lists, chart series, table column formulas and pivot table sources. Conditional formatting rules that refer to the sheet are reported as a warning instead of rewritten.

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Current name of the sheet to rename
newName
- New name for the sheet. Maximum 31 characters, and it cannot contain : \ / ? * [ ]

`excel_delete_sheet`

Delete a sheet. Refuses to delete the last remaining sheet, and refuses to delete a sheet that formulas, data validations, charts, tables or pivot tables elsewhere in the workbook still refer to unless force is set. Defined names pointing at the deleted sheet are removed.

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Name of the sheet to delete
force (optional, default: false)
- Delete even when formulas, data validations, charts, tables or pivot tables elsewhere refer to this sheet, leaving those references broken. The affected places are listed in the tool output.

`excel_move_sheet`

Move a sheet to another position in the tab order. Content and formatting are untouched.

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Name of the sheet to move
index
- Zero-based target position. 0 makes the sheet the first tab, which is the one shown when the workbook is opened.

`excel_delete_rows`

Delete rows and shift the rows below them up. Formatting of the remaining rows, merged cells, column widths, conditional formatting and data validation are preserved. Formulas are adjusted the way Excel adjusts them: references below the deleted rows move up, ranges spanning them shrink, and references pointing only into the deleted rows become #REF!.

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Sheet name in the Excel file
startRow
- First row to delete, one-based and inclusive
endRow
- Last row to delete, one-based and inclusive

`excel_insert_rows`

Insert empty rows and shift the rows at and below the insertion point down. Merged cells, conditional formatting, data validation and formulas move with the rows.

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Sheet name in the Excel file
beforeRow
- One-based row number to insert before
count (optional, default: 1)
- Number of rows to insert

`excel_format_range`

Format cells in the Excel sheet with style information

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Sheet name in the Excel file
range
- Range of cells in the Excel sheet (e.g., "A1:C3")
styles
- 2D array of style objects for each cell. If a cell does not change style, use null. The number of items of the array must match the range size.
- Style object properties:
  - border: Array of border styles (type, color, style)
  - font: Font styling (bold, italic, underline, size, strike, color, vertAlign)
  - fill: Fill/background styling (type, pattern, color, shading)
  - alignment: Cell alignment settings
    - horizontal: Horizontal alignment (left, center, right, fill, justify, centerContinuous, distributed)
    - vertical: Vertical alignment (top, center, bottom, justify, distributed)
    - wrapText: Wrap text in cell (boolean)
    - shrinkToFit: Shrink text to fit cell width (boolean)
    - textRotation: Text rotation angle (0-180, or 255 for vertical)
    - indent: Indent level (0-250)
  - numFmt: Custom number format string
  - decimalPlaces: Number of decimal places (0-30)

`excel_conditional_format`

Set or clear conditional formatting rules on a range — for example, colouring a cell by how its date compares to TODAY().

Reading is covered by excel_read_sheet with showStyle: true, which lists every rule with its formula, its background colour and its priority.

Arguments:

fileAbsolutePath
- Absolute path to the Excel file
sheetName
- Sheet name in the Excel file
range
- Range the rules apply to (e.g., "A1:A11")
operation
- "set" to write the given rules, "clear" to remove the conditional formatting on the range. Defaults to "set".
rules
- Rules to apply, in evaluation order. Required when operation is "set".
- Rule object properties:
  - type: cellIs, expression, containsText, timePeriod, top10, aboveAverage, duplicate, unique, 2_color_scale, 3_color_scale, dataBar
  - operator: comparison for cellIs and text rules (lessThan, lessThanOrEqual, greaterThan, greaterThanOrEqual, equal, notEqual, between, notBetween, containsText, notContains, beginsWith, endsWith)
  - formulas: values or formulas compared against, without a leading =. One entry for most operators, two for between/notBetween, exactly one for an expression rule
  - text: the text a containsText rule looks for
  - stopIfTrue: stop evaluating later rules on this range once this one matches
  - font: font applied on a match (bold, italic, strike, color)
  - fill: background fill applied on a match (type, pattern, color)

Example — colour a date red once it is in the past, amber within 30 days, and leave it alone otherwise:

{
  "fileAbsolutePath": "/path/to/book.xlsx",
  "sheetName": "Sheet1",
  "range": "A1:A11",
  "rules": [
    {"type": "cellIs", "operator": "lessThanOrEqual", "formulas": ["TODAY()"],
     "stopIfTrue": true, "fill": {"type": "pattern", "pattern": "solid", "color": ["#FFC7CE"]}},
    {"type": "cellIs", "operator": "lessThanOrEqual", "formulas": ["TODAY() + 30"],
     "stopIfTrue": true, "fill": {"type": "pattern", "pattern": "solid", "color": ["#FFEB9C"]}}
  ]
}

Notes:

Rules are evaluated in the order given; stopIfTrue prevents later rules from overriding a match.
Setting rules on a range replaces the rules previously written to that same range. Rules on other ranges are left untouched.
Writing is supported by the cross-platform backend only. On Windows with the workbook open in Excel, the OLE backend refuses rather than risk rewriting formatting it cannot read back.

Configuration

You can change the MCP Server behaviors by the following environment variables:

`EXCEL_MCP_PAGING_CELLS_LIMIT`

The maximum number of cells to read in a single paging operation.
[default: 4000]

License

excel-mcp-server is released under the MIT License

Name		Name	Last commit message	Last commit date
.devcontainer		.devcontainer
.github/workflows		.github/workflows
cmd/excel-mcp-server		cmd/excel-mcp-server
docs		docs
internal		internal
launcher		launcher
scripts		scripts
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitignore		.gitignore
.goreleaser.yaml		.goreleaser.yaml
.npmignore		.npmignore
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
go.mod		go.mod
go.sum		go.sum
package-lock.json		package-lock.json
package.json		package.json
projectBrief.md		projectBrief.md
smithery.yaml		smithery.yaml
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

Excel MCP Server

Why Fork?

Features

Requirements

Supported file formats

Installation

Installing via NPM

Installing via Smithery

Tools

`excel_describe_sheets`

`excel_read_sheet`

`excel_screen_capture`

`excel_write_to_sheet`

`excel_create_table`

`excel_copy_sheet`

`excel_rename_sheet`

`excel_delete_sheet`

`excel_move_sheet`

`excel_delete_rows`

`excel_insert_rows`

`excel_format_range`

`excel_conditional_format`

Configuration

`EXCEL_MCP_PAGING_CELLS_LIMIT`

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Excel MCP Server

Why Fork?

Features

Requirements

Supported file formats

Installation

Installing via NPM

Installing via Smithery

Tools

excel_describe_sheets

excel_read_sheet

excel_screen_capture

excel_write_to_sheet

excel_create_table

excel_copy_sheet

excel_rename_sheet

excel_delete_sheet

excel_move_sheet

excel_delete_rows

excel_insert_rows

excel_format_range

excel_conditional_format

Configuration

EXCEL_MCP_PAGING_CELLS_LIMIT

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

`excel_describe_sheets`

`excel_read_sheet`

`excel_screen_capture`

`excel_write_to_sheet`

`excel_create_table`

`excel_copy_sheet`

`excel_rename_sheet`

`excel_delete_sheet`

`excel_move_sheet`

`excel_delete_rows`

`excel_insert_rows`

`excel_format_range`

`excel_conditional_format`

`EXCEL_MCP_PAGING_CELLS_LIMIT`