Model or dataset
haris-musa/excel-mcp-server avatar
haris-musa/excel-mcp-server

excel-mcp-server: An MCP Tool Server for Excel Workbooks Without Excel

A Model Context Protocol server for Excel file manipulation

4,307 stars486 forksPythonMIT

At a glance

What is it?
excel-mcp-server is a Python-based Model Context Protocol server that lets AI agents create, read, and modify Excel files over stdio or HTTP. It covers formatting, charts, pivot tables, and validation, but remote use requires careful path handling.
Who is it for?
Adopt excel-mcp-server if you need an LLM agent to manipulate .xlsx files programmatically without Microsoft Excel installed, especially in local stdio setups where you control file paths. Over Streamable HTTP, plan for workbooks to live in the --allow-dir folder, with export_workbook and import_workbook moving files between server and client.
Can I use it commercially?
Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • haris-musa/excel-mcp-server4,307 ★ · +132
Star history
Repository2026-09-102026-11-15
haris-musa/excel-mcp-server4.2k4.3k

132 Stars in the last 66 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

What It Solves and Who It Is For

The project addresses a narrow but real gap: giving AI agents a way to work with Excel workbooks without requiring the desktop application. The README states it lets you manipulate Excel files without Microsoft Excel installed, and the feature list covers create, read, and update operations. The intended user is someone running an MCP client, such as Cursor or another agent host, who wants that agent to generate reports, edit spreadsheets, or build charts on demand. It is not a spreadsheet application itself. It is a server that exposes Excel operations as tools to an LLM. That makes it useful for automation pipelines where a human would otherwise have to open Excel, run a macro, or write a one-off Python script.

Transport Options and Their Trade-offs

The README documents two ways to run the server. Stdio runs as a local subprocess and is what every client in the quick start uses, via uvx excel-mcp-server stdio. Streamable HTTP is the remote option: uvx excel-mcp-server streamable-http --allow-dir /srv/workbooks, with clients connecting to http://127.0.0.1:8017/mcp. The server listens on localhost only; to accept other machines, the README says to set a token and a host. The repository Dockerfile runs the streamable-http transport, exposes port 8017 and sets EXCEL_MCP_HOST=0.0.0.0.

File Path Handling: The Critical Constraint

File access is controlled with --allow-dir. With --allow-dir DIR, the server only opens workbooks inside DIR (subfolders included), and relative paths such as reports/q1.xlsx start there. Repeat the flag to allow several folders, or set EXCEL_FILES_PATH, separating folders with: on macOS and Linux and; on Windows. Without --allow-dir, any absolute path to an Excel file works. In every mode the server only touches Excel files and never silently overwrites an existing workbook. For remote use, workbooks live in the --allow-dir folder (default ./excel_files), and export_workbook and import_workbook move files between the server and the client.

Getting It Running

You need uv. Every client runs the server with uvx excel-mcp-server stdio, replacing /path/to/workbooks with the folder the server may use. For Claude Code the README gives claude mcp add excel --scope user -- uvx excel-mcp-server stdio --allow-dir /path/to/workbooks; Cursor and most clients that use an mcpServers config get a JSON entry whose command is uvx and whose args are excel-mcp-server, stdio, --allow-dir and the folder. Claude Desktop can instead download excel-mcp-server.mcpb from the latest release and open it. Desktop apps often cannot find uvx because they do not see your shell's PATH, so the README says to use the full path that which uvx prints. The project is on PyPI, and v2.2.6 is the latest release.

What the Tools Cover

The feature list is broad. It covers charts (including the Excel 2016 chart types), PivotTables with slicers and timelines, sparklines, formulas calculated by a built-in engine of about 260 functions, dynamic arrays, formula tracing and Goal Seek, tables, conditional formatting (scales, data bars, icon sets and more), data validation, sorting and filtering, formatting and sheet protection. Reads stream the workbook and return pages, and every call is bounded by size and cell limits. The repository's pyproject.toml points to TOOLS.md as the documentation, so if your use case depends on a specific Excel feature, read TOOLS.md for the exact tool behaviour.

Limitations and Wrong-Tool Cases

The server does not need Excel; it is built on openpyxl and edits files directly. It never runs macros: it reads the VBA code in .xlsm files, and writing VBA is off unless you start it with --allow-vba-write. Threaded comments, shapes, form controls and other content the tools cannot edit are kept as they are rather than edited. Over Streamable HTTP it listens on localhost only until you set a token and a host. This is the wrong tool for scenarios requiring fine-grained control over workbook internals that the tool set does not expose.

A Concrete Alternative

A direct alternative is to use the openpyxl or pandas libraries in a custom Python script that your agent executes. That approach differs in a fundamental way: instead of a generic MCP server exposing fixed tools, you write code that imports openpyxl and performs exactly the operations you need. The server abstracts those library calls into MCP tool calls, which is convenient but also constrains you to the operations the server author chose to expose. With openpyxl, you have full access to the library's API, including features that may not be in this server's tool list. The trade-off is that your agent must have a code execution environment, and you must handle file paths and security yourself. The MCP server centralizes that logic and provides a consistent interface, but it also adds a layer between your agent and the underlying library.

Maintenance and License Considerations

The project is under the MIT License, which permits commercial use, modification, and redistribution with attribution. That is permissive and unlikely to block adoption. The release history shows three releases on 2026-10-31: v2.2.4, v2.2.5 (labelled a security release) and v2.2.6, and the last push was on 2026-11-02. The repository is not archived. A CHANGELOG.md sits in the repository root and is linked from pyproject.toml, so check it before upgrading. For a production deployment, you should pin the version you use and test the specific tools you rely on after any upgrade.

Editorial conclusion

Adopt excel-mcp-server if you need an LLM agent to manipulate .xlsx files programmatically without Microsoft Excel installed, especially in local stdio setups where you control file paths. Over Streamable HTTP, plan for workbooks to live in the --allow-dir folder, with export_workbook and import_workbook moving files between server and client. Before deploying, verify that the tool set in TOOLS.md covers your required operations (charts, pivot tables, conditional formatting) and test the streamable HTTP transport with your client, which connects to http://127.0.0.1:8017/mcp.

Frequently asked questions

How do I install the excel mcp server?

You need uv, and every client runs the server with `uvx excel-mcp-server stdio`, replacing `/path/to/workbooks` with the folder it may use. Claude Desktop instead downloads `excel-mcp-server.mcpb` from the latest release and opens it.

Is there an Excel MCP server?

Yes. It is a Model Context Protocol server that lets assistants create, read and edit Excel workbooks with no Microsoft Excel installation, working with `.xlsx`, `.xlsm`, `.xltx` and `.xltm` files.

Does the excel-mcp-server calculate formulas?

Yes. A built-in engine of about 260 functions calculates formulas without Excel, so `read_range` returns values for files that were never opened in Excel.

Can excel-mcp-server read or run VBA macros?

It reads the VBA code in `.xlsm` files module by module, and never runs it. Macros are preserved rather than stripped when a workbook is saved.

How do I limit which folders excel-mcp-server can open?

Pass `--allow-dir DIR`, which confines it to that folder and its subfolders and resolves relative paths such as `reports/q1.xlsx` from there. Repeat the flag for several folders, or set `EXCEL_FILES_PATH` with `:` on macOS and Linux and `;` on Windows. Without the flag, any absolute path to an Excel file works.

Official sources

  1. haris-musa/excel-mcp-server on GitHub
  2. License: MIT
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/haris-musa-excel-mcp-server.svg)](https://hysenlabs.com/projects/haris-musa-excel-mcp-server)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/haris-musa-excel-mcp-server.svg)](https://hysenlabs.com/projects/haris-musa-excel-mcp-server)

Was this useful?