xlwings-mcp-server

A Model Context Protocol (MCP) server that manipulates Excel files using xlwings - providing native Excel integration through COM automation.

🎯 Why xlwings Instead of openpyxl?

This MCP server is specifically designed for corporate environments where:

🔒 Document security policies prevent direct file access
🏢 Excel files are managed by enterprise document management systems
📊 You need to work with Excel through official Microsoft APIs
✅ IT compliance requires using approved COM automation

Key difference: While openpyxl directly reads/writes Excel files (which may be blocked by security policies), xlwings controls Excel through Microsoft's official COM interface - the same way VBA macros work. This means if you can run Excel macros, you can use this MCP server.

🙏 Acknowledgments

This project is based on excel-mcp-server by Haris Musa.

The original excel-mcp-server uses openpyxl for Excel manipulation. This fork has been modified to use xlwings instead, which provides:

Native Excel COM automation
Better compatibility with complex Excel features
Real-time Excel interaction
Support for Excel-specific features like native pivot tables and charts

📋 License

This project is licensed under the MIT License - see the LICENSE file for details.

🚀 Features

All 25 tools from the original excel-mcp-server are fully functional:

Core Excel Operations

✅ Create, open, save workbooks
✅ Manage worksheets (create, copy, rename, delete)
✅ Read and write data with validation
✅ Apply formulas and validate syntax
✅ Format cells and ranges

Advanced Features

✅ Native Excel charts through COM
✅ Real pivot tables (not just data summaries)
✅ Excel tables (ListObjects)
✅ Cell merging and unmerging
✅ Row and column operations
✅ Range operations (copy, delete)
✅ Data validation info

📦 Installation

Prerequisites

Python 3.10+
Microsoft Excel (required for xlwings)
Windows (recommended) or macOS with Excel

Option 1: Install from PyPI (Recommended)

pip install xlwings-mcp-server

Option 2: Install from Source

Clone the repository:

git clone https://github.com/hyunjae-labs/xlwings-mcp-server.git
cd xlwings-mcp-server

Create virtual environment:

python -m venv .venv
.venv\Scripts\activate  # Windows
# or
source .venv/bin/activate  # macOS/Linux

Install in development mode:

pip install -e .

🔧 Configuration

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "xlwings-mcp-server": {
      "type": "stdio",
      "command": "C:\\path\\to\\xlwings-mcp-server\\.venv\\Scripts\\python.exe",
      "args": ["-m", "xlwings_mcp", "stdio"]
    }
  }
}

📚 Available Tools

The server provides 25 tools for Excel manipulation:

Workbook Operations (3)

create_workbook - Create new Excel file
create_worksheet - Add new worksheet
get_workbook_metadata - Get workbook information

Data Operations (5)

write_data_to_excel - Write data to cells
read_data_from_excel - Read cell data
apply_formula - Apply Excel formulas
validate_formula_syntax - Validate formula syntax
validate_excel_range - Validate cell ranges

Formatting & Visual (5)

format_range - Apply cell formatting
create_chart - Create Excel charts
create_pivot_table - Create pivot tables
create_table - Create Excel tables
merge_cells - Merge cell ranges

Sheet Management (6)

copy_worksheet - Copy worksheets
delete_worksheet - Delete worksheets
rename_worksheet - Rename worksheets
unmerge_cells - Unmerge cells
get_merged_cells - Get merged cell info
copy_range - Copy cell ranges

Row/Column Operations (6)

delete_range - Delete cell ranges
get_data_validation_info - Get validation rules
insert_rows - Insert rows
insert_columns - Insert columns
delete_sheet_rows - Delete rows
delete_sheet_columns - Delete columns

🔄 When to Use Which?

Use excel-mcp-server (Original) when:

✅ You don't have Excel installed
✅ You need cross-platform support
✅ You want faster performance
✅ Simple Excel operations are sufficient

Use xlwings-mcp-server (This Fork) when:

✅ Corporate security blocks direct file access
✅ You need to work with protected/encrypted Excel files
✅ You require native Excel features (real pivot tables, complex charts)
✅ Your organization mandates using official Microsoft APIs
✅ You need real-time Excel integration

Feature	excel-mcp-server (Original)	xlwings-mcp-server (This Fork)
How it works	Direct file manipulation	Controls Excel application
Security Policy	May be blocked	Works if macros are allowed
Excel Required	No	Yes
Best for	Personal use, servers	Corporate environments

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

📄 Citation

If you use this project, please acknowledge both:

The original excel-mcp-server by Haris Musa
This xlwings modification

🔗 Links

Original Project: excel-mcp-server
xlwings Documentation: xlwings.org
MCP Protocol: Model Context Protocol

xlwings-mcp-server