excel-mcp-server: an MCP server for editing Excel workbooks without Excel installed

The gap excel-mcp-server fills: agents that need to write .xlsx, not describe it

Most LLM tooling around spreadsheets stops at reading. An agent can be handed a CSV dump, or a sheet exported to text, and reason about the numbers. The moment the deliverable is a workbook with formulas, merged headers, a chart on a second sheet and a pivot table, the text pipeline breaks: something has to write the binary file, and on a server that something is usually not Excel.

excel-mcp-server takes the position that the agent should call tools that manipulate the workbook directly. The README frames it plainly: a Model Context Protocol server that lets you manipulate Excel files without needing Microsoft Excel installed, so that you can create, read and modify workbooks with your AI agent. The target user is therefore not an analyst clicking around a spreadsheet. It is an engineer wiring an MCP client (Claude, Cursor, or anything else that speaks the protocol) into a workflow where the output artifact is a .xlsx file.

The feature list is broad for a project at version 0.1.8: workbook and worksheet creation, formulas, formatting, charts, pivot tables, Excel tables, data validation, and sheet management such as copy, rename and delete. Breadth here is a signal about scope, not about depth. The README defers the actual tool inventory to a separate TOOLS.md file, which is where you should look before assuming a specific operation exists.

How the server is put together: FastMCP, openpyxl, and three transports

The dependency list in pyproject.toml tells most of the architecture. The server is built on fastmcp (>=2.0.0,<3.0.0) with mcp[cli]>=1.10.1, and the actual file manipulation is delegated to openpyxl>=3.1.5. Typer handles the command line entry point, exposed as the console script excel-mcp-server, which maps to excel_mcp.__main__:app. Python 3.10 or newer is required, and the build backend is hatchling with the package rooted at src/excel_mcp.

So the data flow is: MCP client sends a tool call, FastMCP routes it to a Python function, that function opens or writes a workbook through openpyxl, and the result goes back over the transport. Nothing in the stack requires a Microsoft runtime. That is the whole point, and it is also the source of the limitations discussed below, because openpyxl is not Excel.

Transport handling is where the deployment decisions live. The README documents three modes: stdio for local use, SSE which it explicitly marks as deprecated, and streamable HTTP which it recommends for remote connections. The choice is not cosmetic. Under stdio, the file path travels with each tool call, so the server uses whatever path the client sends. Under SSE or streamable HTTP, the server is a long-lived process with a fixed view of the filesystem, and the README states that you must set EXCEL_FILES_PATH on the server side to tell it where to read and write.

Installing excel-mcp-server and making a first workbook through stdio

The README gives uvx as the install-and-run path, so no separate pip install step is documented. The stdio command is a single line, and the server starts as a child process of whichever MCP client launches it.

uvx excel-mcp-server stdio

Running that by hand will start a server that waits for protocol messages on stdin, which is not useful interactively. The intended use is to register it with a client. The README gives this JSON shape for an MCP client configuration:

{
   "mcpServers": {
      "excel": {
         "command": "uvx",
         "args": ["excel-mcp-server", "stdio"]
      }
   }
}

After the client restarts, the Excel tools should appear in its tool list. Because this is stdio, you do not set EXCEL_FILES_PATH. The README is explicit that the file path is provided with each tool call, and the server uses the path sent by the client for each operation. In practice that means the first real task is to ask the agent to create a workbook at a path you choose, then add a sheet and write a formula, and then open the file to confirm it. The repository's TOOLS.md is the reference for what those tool names and arguments actually are; the README does not inline them.

For a remote setup the shape changes. The README shows the streamable HTTP invocation and a client entry pointing at a URL rather than a command:

EXCEL_FILES_PATH=/path/to/excel_files FASTMCP_PORT=8007 uvx excel-mcp-server streamable-http

{
   "mcpServers": {
      "excel": {
         "url": "http://localhost:8000/mcp"
      }
   }
}

Two things are easy to get wrong here. The default port in the README's environment variable section is 8017, while the example client URL uses 8000, so the URL you configure has to match whatever FASTMCP_PORT you actually set. And EXCEL_FILES_PATH defaults to ./excel_files if unset, which in a container may be a directory you did not intend to write to.

The file path rules under HTTP are the part that will bite you

When the server runs over SSE or streamable HTTP, the README says tool filepath values must be relative to EXCEL_FILES_PATH, giving reports/q1.xlsx as the example. Absolute paths and directory traversal are rejected. That is a deliberate containment boundary, and it is the right default for a service that an agent can drive, since an unrestricted path argument would let a model write anywhere the process user can reach.

The cost is that the server cannot touch a workbook outside that one directory tree. If your pipeline produces files in /mnt/uploads and archives them in /mnt/archive, you either point EXCEL_FILES_PATH at a common parent or you run multiple server instances. There is no documented per-call override. The README does not describe a way to widen the boundary at runtime, and it does not document what error the client sees when a traversal attempt is rejected.

Under stdio the constraint disappears, which cuts both ways. The client supplies the path, so the agent can reach any file the process user can read or write. That is convenient for a local desktop setup and inappropriate for anything shared, because the trust boundary is now the MCP client itself.

What openpyxl cannot give you, and when to pick something else

The README's promise of charts, pivot tables, conditional formatting and Excel tables is a promise about writing them, not about preserving everything that was already in a file. Because the manipulation layer is openpyxl, the fidelity ceiling is openpyxl's, and the README does not document round-trip guarantees for existing workbooks. If your workflow is read an existing quarterly model, change three cells, save it back, and expect every chart, external link and cached pivot cache to survive, that is the scenario to test before committing. The documentation is silent on it.

The same applies to formulas. The server can write a formula into a cell, but nothing in the documentation suggests it evaluates one. A workbook produced by an agent will show whatever the last writer put in the cell cache until something opens it in a real spreadsheet application and recalculates. If your downstream consumer reads values rather than formulas, plan for that.

There is also the version number. v0.1.8 landed on 2026-04-12, and the previous two releases, v0.1.6 and v0.1.7, both landed in August 2025. The repository is not archived, but with the last push on 2026-04-12 it is not being changed daily either. TOOLS.md is the contract, and a 0.1.x contract can move.

For a genuinely different approach, consider a general Python scripting tool that lets the agent write and execute openpyxl code directly rather than calling a fixed tool set. The difference is where the flexibility sits. excel-mcp-server constrains the agent to a curated list of operations, which makes calls predictable and auditable, and means the model cannot accidentally run arbitrary code. A code-execution tool gives the agent the full openpyxl API, including the parts this server does not wrap, at the cost of a much larger blast radius and no schema to validate against. If your needs are already covered by the tools in TOOLS.md, the constrained server is the safer integration. If they are not, no amount of configuration will add them.

Licence, packaging and what an upgrade actually costs

The project is MIT licensed, and the README points at the LICENSE file for the text. For most teams that means the usual permissive terms: keep the copyright notice, and you can ship it inside a commercial product. This is not legal advice, and if you are redistributing the .mcpb bundle or embedding the server in a product, have counsel read the actual file rather than the badge.

The packaging surface is worth noting because it affects upgrade work. Beyond the PyPI distribution, the repository root contains excel-mcp-server-0.1.8.mcpb, a manifest.json, and a .mcpbignore, which indicates a bundled MCP package alongside the Python one. There is also a smithery listing referenced by a badge in the README. Each of those distribution channels can lag the PyPI release, so pinning by version matters more than usual.

Upgrade cost is dominated by the tool schema, not the dependency graph. The runtime dependencies are few and stable: mcp[cli], fastmcp pinned below 3.0.0, openpyxl and typer. The riskier change is a tool being renamed, having an argument added, or a default shifting between 0.1.x releases, because that silently breaks an agent prompt that was written against the old schema. The README does not document a deprecation policy or a changelog for tool changes, so the practical approach is to pin the version in whatever launches the server and diff TOOLS.md before moving. The SSE transport is already marked deprecated in the README, which is a concrete example of the kind of change that arrives without a migration guide.

Editorial conclusion

Adopt it if you want an agent to generate or patch .xlsx files on a Linux box or container where Microsoft Excel is not installed, and you are comfortable with a 0.1.x API whose tool list lives in TOOLS.md rather than the README. Do not adopt it if you need a hosted multi-tenant document service, if your workbooks must round-trip existing charts and pivot tables untouched, or if you need Excel itself to recalculate formulas. Verify first that the tools you need are actually listed in TOOLS.md, that your client can launch uvx with the stdio argument, and that EXCEL_FILES_PATH and FASTMCP_PORT are set the way your deployment expects before you point an agent at a shared directory.

Frequently asked questions

Official sources

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