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
• 💰 Token Optimization: Preview mode, row limits, lightweight output for cost savings

Token Optimization

This server includes built-in token-saving features to reduce API costs when working with large Excel files.

Preview Mode

Use preview_only=True to limit data to the first 50 rows:

{
  "name": "read_data_from_excel",
  "arguments": {
    "filepath": "/path/to/file.xlsx",
    "sheet_name": "Sheet1",
    "preview_only": true
  }
}

Custom Row Limit

Use max_rows to specify exact number of rows:

{
  "name": "read_data_from_excel",
  "arguments": {
    "filepath": "/path/to/file.xlsx",
    "sheet_name": "Sheet1",
    "max_rows": 100
  }
}

Lightweight Mode

For maximum token savings, use read_data_lightweight which returns only cell values without metadata:

{
  "name": "read_data_lightweight",
  "arguments": {
    "filepath": "/path/to/file.xlsx",
    "sheet_name": "Sheet1",
    "preview_only": true
  }
}

Comparison:

Mode	Output	Token Savings
read_data_from_excel (full)	Full metadata + validation	0%
read_data_from_excel (preview_only)	First 50 rows	~80%
read_data_from_excel (no empty cells)	Skips null cells	~30%
read_data_lightweight	Values only	~90%

Token-Saving Parameters

Parameter	Description	Default
preview_only	Limit to 50 rows	false
max_rows	Custom row limit	null
max_cols	Custom column limit	null
include_empty_cells	Include null cells	false
include_validation	Include validation metadata (read_data_from_excel only)	true

MCP Configuration

Using Pre-built Binary (.mcpb)

The project provides a pre-compiled binary file excel-mcp-server-0.1.7.mcpb for easy deployment.

Cursor / Claude Code:

{
  "mcpServers": {
    "excel-mcp": {
      "command": "/path/to/excel-mcp-server-0.1.7.mcpb",
      "args": ["stdio"]
    }
  }
}

Claude Desktop (config.json):

{
  "mcpServers": {
    "excel-mcp": {
      "command": "/path/to/excel-mcp-server-0.1.7.mcpb",
      "args": ["stdio"]
    }
  }
}

Using uvx (Recommended)

Claude Code / Cursor:

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

Environment Variables

Variable	Description	Default
EXCEL_FILES_PATH	Base directory for file operations	./excel_files
FASTMCP_PORT	HTTP/SSE server port	8017
FASTMCP_HOST	HTTP/SSE server host	0.0.0.0
EXCEL_ALLOWED_PATHS	Allowed path whitelist (comma-separated)	(empty)
EXCEL_MAX_SIZE_MB	Maximum file size in MB (prevents OOM)	100
EXCEL_MAX_CONCURRENT	Max concurrent requests (0=unlimited)	10
EXCEL_PREVIEW_ROWS	Default preview row limit	50
EXCEL_GC_INTERVAL	Operations between GC (0=disabled)	50
EXCEL_GC_THRESHOLD_MB	Memory threshold to trigger GC (0=disabled)	512
EXCEL_PIVOT_MAX_ROWS	Maximum source rows for pivot tables	100000
EXCEL_PIVOT_MAX_COMBINATIONS	Maximum pivot combinations (prevents memory explosion)	10000
EXCEL_IGNORE_MULTIPROCESS_WARNING	Suppress multi-process deployment warning	false

Deployment Considerations

Single-Process Deployment (Recommended)

The concurrency control (EXCEL_MAX_CONCURRENT) uses threading semaphores which only work within a single process. For predictable behavior:

• stdio mode: Always single-process, fully supported
• HTTP/SSE mode: Use workers=1 or single-process deployment

If you must use multi-process deployment (e.g., Gunicorn with multiple workers), the actual max concurrent requests will be EXCEL_MAX_CONCURRENT × workers. Adjust accordingly or set EXCEL_IGNORE_MULTIPROCESS_WARNING=true to suppress the startup warning.

Security Configuration

Restrict file access to specific directories:

EXCEL_ALLOWED_PATHS="/data/excel,/home/user/documents" uvx excel-mcp-server stdio

Usage

The server supports three transport methods:

1. Stdio Transport (for local use)

uvx excel-mcp-server stdio

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

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

uvx excel-mcp-server sse

SSE transport connection:

{
   "mcpServers": {
      "excel": {
         "url": "http://localhost:8000/sse",
      }
   }
}

3. Streamable HTTP Transport (Recommended for remote connections)

uvx excel-mcp-server streamable-http

Streamable HTTP transport connection:

{
   "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):

  $env:EXCEL_FILES_PATH="E:\MyExcelFiles"
  $env:FASTMCP_PORT="8007"
  uvx excel-mcp-server streamable-http

• Example (Linux/macOS):

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

Stdio Transport

When using the stdio protocol, 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.

Internationalization (i18n)

The server supports localized error messages. By default, error messages are in English.

Enable Chinese Error Messages

Set the EXCEL_MCP_LANG environment variable to zh to enable Chinese error messages:

# Linux/macOS
EXCEL_MCP_LANG=zh uvx excel-mcp-server stdio

# Windows PowerShell
$env:EXCEL_MCP_LANG="zh"
uvx excel-mcp-server stdio

Supported Languages

• en (English) - Default
• zh (Chinese)

Optional Dependencies

XLS Format Support

To work with legacy .xls files, install with XLS support:

uvx --with xlrd --with xlwt --with xlutils excel-mcp-server stdio

Or install locally:

pip install excel-mcp-server[xls]

Memory Monitoring

To enable memory usage monitoring and automatic garbage collection, install with memory support:

pip install excel-mcp-server[memory]

This enables the psutil library for memory threshold-based garbage collection.

Memory and Process Management

Understanding Process Behavior

In stdio mode (the default), each MCP client connection spawns a separate server process. This is normal MCP behavior, but can lead to:

• Multiple excel-mcp-server processes running simultaneously
• Higher memory usage (~50MB per process + Excel file data)
• Process accumulation if sessions don't terminate cleanly

Solution 1: Idle Timeout (Default: Enabled)

The server automatically exits after 10 minutes of inactivity to prevent process accumulation.

Configure timeout:

# Custom timeout (in seconds)
export EXCEL_MCP_IDLE_TIMEOUT=600  # 10 minutes (default)

# Disable timeout (not recommended)
export EXCEL_MCP_IDLE_TIMEOUT=0

Solution 2: Cleanup Stale Processes

Linux/macOS:

# Use the provided cleanup script
./cleanup.sh

# Or manually kill processes
pkill -f "excel-mcp-server"

Windows PowerShell:

Stop-Process -Name "excel-mcp-server" -Force

Solution 3: Use HTTP Mode for Production (Recommended)

For multi-user scenarios or production environments, use streamable HTTP mode instead of stdio:

export EXCEL_FILES_PATH="./excel_files"
export FASTMCP_PORT=8017
uvx excel-mcp-server streamable-http

Benefits:

• ✅ Single server process handles all requests
• ✅ Better resource management
• ✅ No process accumulation

Client configuration:

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

Environment Variables Reference

Variable	Default	Description
EXCEL_MCP_IDLE_TIMEOUT	600	Seconds of inactivity before auto-exit (0 = disabled)
EXCEL_FILES_PATH	./excel_files	Base directory for Excel files (SSE/HTTP modes)
FASTMCP_PORT	8017	Server port for HTTP modes
EXCEL_MAX_SIZE_MB	100	Maximum file size limit (MB)
EXCEL_MAX_CONCURRENT	10	Max concurrent requests per process
EXCEL_CACHE_SIZE	3	Max cached workbooks per process
EXCEL_CACHE_MEMORY_MB	500	Max cache memory per process (MB)
EXCEL_GC_INTERVAL	50	Operations between full garbage collections
EXCEL_GC_THRESHOLD_MB	512	Memory threshold to trigger immediate GC (MB)
EXCEL_MCP_LANG	en	Error message language (en or zh)

Troubleshooting

High Memory Usage:

1. Check processes: ps aux | grep excel-mcp
2. Kill stale processes: ./cleanup.sh
3. Reduce cache: export EXCEL_CACHE_SIZE=1
4. Lower memory threshold: export EXCEL_GC_THRESHOLD_MB=256

Too Many Processes:

1. Verify idle timeout is enabled (default)
2. Ensure MCP client sessions are properly closed
3. Consider switching to HTTP mode

For detailed guidance, see Memory Management Guide (中文).

Available Tools

The server provides 24 tools covering the following categories:

Workbook Operations

• create_workbook — Create new Excel workbook
• create_worksheet — Create new worksheet
• get_workbook_metadata — Get workbook metadata and structure

Data Operations

• write_data_to_excel — Write data to Excel cells
• read_data_from_excel — Read data from Excel range (with validation metadata)
• read_data_lightweight — Lightweight read (streaming optimized, values only)
• read_data_paginated — Paginated reading (for large files)
• read_data_streaming — Streaming chunk reading (for batch processing large files)

Large File Handling

For large Excel files (>100MB), use optimized reading modes with 90%+ memory reduction:

1. Lightweight Mode (read_data_lightweight)

• Uses iter_rows(values_only=True) for streaming reads
• Reduces memory usage by 90%+
• Returns only cell values (2D array), no metadata
• Supports max_cols parameter to limit column count for wide datasets
• Ideal for quick previews and value-only scenarios

2. Paginated Mode (read_data_paginated)

• Reads data in pages by page number and size
• Only loads one page into memory per call
• Returns metadata like total pages and whether more data exists
• Perfect for interactive viewing and page-by-page processing

{
"name": "read_data_paginated",
"arguments": {
"filepath": "/path/to/large.xlsx",
"sheet_name": "Sheet1",
"page": 1,
"page_size": 100
}
}

3. Streaming Chunk Mode (read_data_streaming)

• Returns data in chunks by chunk_size
• Memory usage drops from O(n) to O(chunk_size)
• Suitable for batch processing files over 100MB
• Returns a generator, cannot be re-iterated

{
"name": "read_data_streaming",
"arguments": {
"filepath": "/path/to/large.xlsx",
"sheet_name": "Sheet1",
"chunk_size": 100
}
}

4. Metadata Mode (read_data_from_excel)

• Includes full cell metadata (validation rules, formatting, etc.)
• Use preview_only=true to limit to first 50 rows
• Use include_validation=false to skip validation metadata for better performance
• For scenarios requiring validation info and high fidelity

Recommended Configuration

# .env configuration
EXCEL_PREVIEW_ROWS=50 # Row limit for preview mode
EXCEL_PREVIEW_COLS=20 # Column limit for preview mode
EXCEL_MAX_SIZE_MB=100 # Maximum file size (MB)
EXCEL_GC_THRESHOLD_MB=512 # Memory threshold to trigger GC (MB)

Best Practices

• Files < 100MB: Use read_data_from_excel + preview_only=true
• Files 100-500MB: Use read_data_paginated for paginated reading
• Files > 500MB: Use read_data_streaming for batch processing

Formatting

• format_range — Apply formatting (bold, italic, colors, borders, etc.)
• merge_cells / unmerge_cells — Merge/unmerge cells
• get_merged_cells — List merged cell ranges

Formulas

• apply_formula — Apply Excel formula to cell
• validate_formula_syntax — Validate formula syntax

Charts and Tables

• create_chart — Create charts (line, bar, pie, scatter, etc.)
• create_pivot_table — Create pivot table
• create_table — Create styled Excel table

Worksheet Management

• copy_worksheet — Copy worksheet within workbook
• delete_worksheet — Delete worksheet
• rename_worksheet — Rename worksheet
• insert_rows / insert_columns — Insert rows/columns
• delete_sheet_rows / delete_sheet_columns — Delete rows/columns

Range Operations

• copy_range — Copy cell range to another location
• delete_range — Delete cell range content
• validate_excel_range — Validate range format/existence
• get_data_validation_info — Get data validation rules

For complete tool documentation, see TOOLS.md.

Star History

License

MIT License - see LICENSE for details.