Metadata-Version: 2.4
Name: mcp-excel-tools
Version: 0.1.8
Summary: Excel MCP Server for manipulating Excel files
Author-email: chnwine <chnwine@qq.com>
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: fastmcp<3.0.0,>=2.0.0
Requires-Dist: mcp[cli]>=1.10.1
Requires-Dist: openpyxl>=3.1.5
Requires-Dist: typer>=0.16.0
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/optltd/mcp-excel-tools/main/assets/logo.svg" alt="Excel MCP Tools Logo" width="300"/>
</p>

[![PyPI version](https://img.shields.io/pypi/v/mcp-excel-tools.svg)](https://pypi.org/project/mcp-excel-tools/)
[![Total Downloads](https://static.pepy.tech/badge/mcp-excel-tools)](https://pepy.tech/project/mcp-excel-tools)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)


A Model Context Protocol (MCP) server that lets you manipulate Excel files without needing Microsoft Excel installed. Create, read, and modify Excel workbooks with your AI agent.

## Features

- 📊 **Excel Operations**: Create, read, update workbooks and worksheets
- 📈 **Data Manipulation**: Formulas, formatting, charts, pivot tables, and Excel tables
- 🔍 **Data Validation**: Built-in validation for ranges, formulas, and data integrity
- 🎨 **Formatting**: Font styling, colors, borders, alignment, and conditional formatting
- 📋 **Table Operations**: Create and manage Excel tables with custom styling
- 📊 **Chart Creation**: Generate various chart types (line, bar, pie, scatter, etc.)
- 🔄 **Pivot Tables**: Create dynamic pivot tables for data analysis
- 🔧 **Sheet Management**: Copy, rename, delete worksheets with ease
- 🔌 **Triple transport support**: stdio, SSE (deprecated), and streamable HTTP
- 🌐 **Remote & Local**: Works both locally and as a remote service

## Usage

The server supports three transport methods:

### 1. Stdio Transport (for local use)

```bash
uvx mcp-excel-tools stdio
```

```json
{
   "mcpServers": {
      "excel": {
         "command": "uvx",
         "args": ["mcp-excel-tools", "stdio"]
      }
   }
}
```

### 2. SSE Transport (Server-Sent Events - Deprecated)

```bash
uvx mcp-excel-tools sse 
```

**SSE transport connection**:
```json
{
   "mcpServers": {
      "excel": {
         "url": "http://localhost:8000/sse",
      }
   }
}
```

### 3. Streamable HTTP Transport (Recommended for remote connections)

```bash
uvx mcp-excel-tools streamable-http
```

**Streamable HTTP transport connection**:
```json
{
   "mcpServers": {
      "excel": {
         "url": "http://localhost:8000/mcp",
      }
   }
}
```

## Environment Variables & File Path Handling

### SSE and Streamable HTTP Transports

When running the server with the **SSE or Streamable HTTP protocols**, you **must set the `EXCEL_FILES_PATH` environment variable on the server side**. This variable tells the server where to read and write Excel files.
- If not set, it defaults to `./excel_files`.

You can also set the `FASTMCP_PORT` environment variable to control the port the server listens on (default is `8017` if not set).
- Example (Windows PowerShell):
  ```powershell
  $env:EXCEL_FILES_PATH="E:\MyExcelFiles"
  $env:FASTMCP_PORT="8007"
  uvx mcp-excel-tools streamable-http
  ```
- Example (Linux/macOS):
  ```bash
  EXCEL_FILES_PATH=/path/to/excel_files FASTMCP_PORT=8007 uvx mcp-excel-tools streamable-http
  ```

### Stdio Transport

When using the **stdio protocol**, <del>the file path is provided with each tool call, so you do **not** need to set `EXCEL_FILES_PATH` on the server. The server will use the path sent by the client for each operation.</del>

set `EXCEL_FILES_PATH` can help agent as soon as possible to find the Excel file, actually every tool's env and base path diffent another one, but they should resolve the relative path to absolute path.

## Available Tools

The server provides a comprehensive set of Excel manipulation tools. See [TOOLS.md](TOOLS.md) for complete documentation of all available tools.

## Thanks

this project is based on [excel-mcp-server](https://github.com/haris-musa/excel-mcp-server), thanks for the original work.

- [excel-mcp-server](https://github.com/haris-musa/excel-mcp-server)

## License

MIT License - see [LICENSE](LICENSE) for details.
