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.

The original excel-mcp-server is also MIT licensed. Copyright (c) 2025 Haris.

🚀 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

1. Clone the repository:

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

2. Create virtual environment:

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

3. 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:

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

🔗 Links

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