excel-mcp-server 0.2.1

An MCP server that exposes Excel manipulation tools over stdio and streamable HTTP transports
Documentation

Excel MCP Server

A high-performance Model Context Protocol (MCP) server that gives AI assistants full control over Excel spreadsheets. Built in Rust with zavora-xlsx for native xlsx read/write and rmcp for the MCP protocol layer.

74 tools covering the complete Excel feature set — cell I/O, formatting, 14 chart types, pivot tables with calculated fields, slicers, timelines, form controls, conditional formatting, data validation, images, shapes, threaded comments, formula recalculation, encrypted save/open, and more.

Install

cargo install excel-mcp-server

This compiles and installs the binary to ~/.cargo/bin/excel-mcp-server.

Requires Rust 1.85+. If you don't have Rust: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Client Configuration

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "excel": {
      "command": "excel-mcp-server"
    }
  }
}

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "excel": {
      "command": "excel-mcp-server",
      "autoApprove": []
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "excel": {
      "command": "excel-mcp-server"
    }
  }
}

HTTP Mode

For web-based MCP clients:

excel-mcp-server http

Starts a streamable HTTP server on 127.0.0.1:8080. Point your client at http://localhost:8080/mcp.

BIND_ADDRESS=0.0.0.0:3000 excel-mcp-server http

Features

  • Create, open, edit, and save xlsx files through natural language
  • Read and analyze spreadsheets with pagination, search, and CSV export
  • Full formatting — bold, italic, colors, borders, number formats, alignment, merge
  • 14 chart types — bar, column, line, pie, scatter, area, doughnut, waterfall, funnel, treemap, sunburst, histogram, box & whisker, map
  • Chart enhancements — data tables, 3D views, error bars, axis formatting/bounds/log scale, drop lines, high-low lines, gradients, bubble sizes, alt text, preset styles
  • Pivot tables — calculated fields, date/range grouping, subtotals, grand totals, value formats, row stripes, layout options
  • Slicers and timelines — interactive pivot table filters
  • Form controls — buttons, checkboxes, dropdowns, spinners
  • Conditional formatting — cell value rules, 2/3-color scales, data bars, icon sets
  • Data validation — dropdowns, number/date ranges, text length, custom formulas
  • Tables, sparklines, images, shapes — full Excel feature coverage
  • Threaded comments — modern conversation-style comments with replies and timestamps
  • Formula recalculation — 58-function engine with dependency graph, evaluated before every save
  • Multiple save formats — xlsx, template (.xltx), encrypted (password-protected), parallel compression
  • Open encrypted — password-protected workbook support
  • Named ranges — full CRUD with workbook and sheet-level scoping
  • Sheet metadata — read used range, hyperlinks, merged ranges, embedded charts
  • Custom XML parts — add and read custom XML by namespace
  • Custom document properties — text, number, integer, boolean, datetime
  • Two transports — stdio for CLI clients, streamable HTTP for web clients
  • In-memory workbook store — 10-workbook capacity with 30-minute TTL eviction

Tools Reference (74 tools)

Workbook Lifecycle (4)

Tool Description
create_workbook Create a new empty workbook in memory
open_workbook Open an existing xlsx file (edit or read-only mode)
save_workbook Save to disk as xlsx (formulas recalculated automatically)
close_workbook Close and free memory

Workbook Configuration (1)

Tool Description
configure_workbook Set calc mode (auto/manual), active sheet, document properties

Sheet Management (7)

Tool Description
list_sheets List all sheet names
get_sheet_dimensions Get used range, row count, column count
describe_workbook Sheet names, dimensions, and sample data
add_sheet Add a new worksheet
rename_sheet Rename a worksheet
delete_sheet Delete a worksheet
move_worksheet Reorder a worksheet

Reading (4)

Tool Description
read_sheet Read data with optional range and pagination
read_cell Read a cell's value, type, and formula
search_cells Search by value or pattern across sheets
sheet_to_csv Export as CSV string

Writing (5)

Tool Description
write_cells Batch write to multiple cells (auto-detects types)
write_row Write values rightward from a cell
write_column Write values downward from a cell
write_rich_text Write mixed bold/italic/color text runs
write_json_rows Write JSON objects as rows with auto headers and type detection

Formulas (1)

Tool Description
write_formula Regular, array (CSE), or dynamic (Excel 365 spill) formulas

Cell Operations (1)

Tool Description
manage_cell Write formatted blank or clear content/formatting

Formatting (4)

Tool Description
set_cell_format Bold, italic, colors, borders, number format, alignment on a range
merge_cells Merge a range into one cell
set_row_column_format Format an entire row or column
set_dimensions Column width, row height, column range width, default row height

Layout (5)

Tool Description
freeze_panes Freeze rows/columns for scrolling
autofit_columns Auto-fit widths based on content
set_selection Set the active cell
set_visibility Hide/unhide rows or columns
set_sheet_settings Hidden, zoom, gridlines, tab color, right-to-left

Charts (8)

Tool Description
add_chart Bar/column/line/pie/scatter/area/doughnut with series, trendlines, markers, error bars, gradients, axis formatting, data tables, 3D views, alt text, preset styles
add_waterfall_chart Waterfall (ChartEx) with increase/decrease/total points
add_funnel_chart Funnel (ChartEx)
add_treemap_chart Treemap (ChartEx) with per-point colors
add_sunburst_chart Sunburst (ChartEx) for hierarchical data
add_histogram_chart Histogram with bin control and Pareto overlay
add_box_whisker_chart Box & whisker with outliers, mean markers, inner points
add_map_chart Geographic map with country/region levels

Interactive Controls (3)

Tool Description
add_slicer Interactive pivot table filter
add_timeline Date-based pivot table filter
add_form_control Button, checkbox, dropdown, or spinner

Tables & Data Features (4)

Tool Description
add_table Excel Table with headers, autofilter, style
add_conditional_format Cell value, color scales, data bars, icon sets
add_data_validation Dropdowns, number/date ranges, custom formulas
add_sparkline Line, column, or win/loss sparkline

Images & Shapes (2)

Tool Description
add_image Embed PNG or JPEG
add_shape Rectangle, ellipse, arrow, callout, text box with fill and outline

Pivot Tables (1)

Tool Description
add_pivot_table Row/column/value/filter fields, aggregation, calculated fields, date/range grouping, subtotals, grand totals, value formats, layout

Page Setup (1)

Tool Description
set_page_setup Landscape, paper size, margins, fit-to-page, print area, headers/footers, gridlines

Comments & Links (3)

Tool Description
manage_comments Add or read legacy comments/notes
add_threaded_comment Modern threaded comments with replies and timestamps
add_link External URLs or internal sheet references

Named Ranges (2)

Tool Description
manage_defined_names Add or list defined names
manage_named_ranges Full CRUD: add, add_scoped, update, remove, list with scope

Row/Column Manipulation (2)

Tool Description
modify_rows Insert or delete rows
modify_columns Insert or delete columns

Protection (3)

Tool Description
group Group rows/columns into outlines
protect Protect sheet/workbook or unprotect ranges
protect_sheet_advanced Granular protection (allow/deny insert, delete, format, sort per feature)

Autofilter & Errors (2)

Tool Description
manage_autofilter Set autofilter with optional column filtering
ignore_error Suppress green triangle error indicators

Document Properties (2)

Tool Description
set_doc_properties Title, author, subject, description, keywords, category, company
set_custom_property Custom properties (text, number, integer, bool, datetime)

Advanced Save/Open (2)

Tool Description
save_workbook_advanced Save as template, encrypted, or parallel. Formulas recalculated.
open_workbook_encrypted Open password-protected workbooks

Read Enhancements (3)

Tool Description
read_cell_comment Read a single cell's comment
read_cell_format Read a cell's formatting
read_sheet_metadata Used range, hyperlinks, merged ranges, charts — individually or all

Workbook Features (4)

Tool Description
add_chart_sheet Dedicated chart-only sheet
manage_custom_xml Add or read custom XML parts by namespace
add_connection Add external data connection
set_sst_threshold Shared string table optimization threshold

Example Workflow

1. create_workbook {}
   → { workbook_id: "abc-123", sheets: ["Sheet1"] }

2. write_row { workbook_id: "abc-123", sheet_name: "Sheet1",
     start_cell: "A1", values: ["Product", "Q1", "Q2", "Q3", "Q4"] }

3. write_row { ..., start_cell: "A2", values: ["Widget", 150, 200, 180, 220] }

4. set_cell_format { ..., range: "A1:E1", bold: true,
     background_color: "#4472C4", font_color: "#FFFFFF" }

5. add_chart { ..., chart_type: "column",
     series: [{ values: "Sheet1!$B$2:$E$2",
                categories: "Sheet1!$B$1:$E$1", name: "Widget" }],
     title: "Quarterly Sales", cell: "A5",
     style: 26, show_data_table: true }

6. save_workbook { ..., file_path: "./quarterly_report.xlsx" }

Architecture

src/
├── main.rs            Entry point — stdio or HTTP transport
├── server.rs          MCP tool router — 74 tools registered
├── store.rs           In-memory workbook store with TTL eviction
├── lib.rs             Crate root
├── error.rs           Error types
├── cell_ref.rs        A1 notation parsing
├── engines/
│   └── zavora.rs      zavora-xlsx engine adapter + recalculate
├── tools/
│   ├── workbook.rs    create, open, save, close
│   ├── read.rs        read_sheet, read_cell, search, CSV
│   ├── write.rs       write_cells, write_row, write_column
│   ├── format.rs      set_cell_format, merge_cells
│   ├── charts.rs      Basic chart support
│   ├── tables.rs      Excel Tables
│   ├── conditional.rs Conditional formatting
│   ├── validation.rs  Data validation
│   ├── sparklines.rs  Sparklines
│   ├── images.rs      Image embedding
│   ├── layout.rs      Freeze panes
│   ├── sheets.rs      Sheet management
│   └── expanded.rs    All advanced tools (charts, pivots, controls, etc.)
└── types/
    ├── inputs.rs      Input structs for all 74 tools
    ├── enums.rs       Chart types, formats, validation rules
    └── responses.rs   JSON response builders

Workbook Store

  • Capacity: 10 concurrent workbooks
  • TTL: 30-minute inactivity timeout with automatic eviction
  • Thread-safe: Arc<RwLock<WorkbookStore>>
  • Every create_workbook or open_workbook returns a workbook_id handle
  • All operations reference this handle
  • save_workbook recalculates all formulas before writing

Response Format

Success:

{ "status": "success", "message": "...", "data": { ... } }

Error:

{ "status": "error", "category": "not_found", "message": "...", "suggestion": "..." }

Error categories: not_found, io_error, engine_unsupported, capacity_exceeded

Development

git clone https://github.com/zavora-ai/excel-mcp-server.git
cd excel-mcp-server
cargo build --release    # Binary at target/release/excel-mcp-server
cargo test               # Run all tests
cargo clippy             # Lint
cargo fmt                # Format

License

Apache 2.0 — see LICENSE.

Copyright 2025 Zavora Technologies Ltd.