Skip to main content
Glama

xlwings Excel MCP Server

by hyunjae-labs

xlwings-mcp-server

Version Python License MCP

A robust Model Context Protocol (MCP) server for Excel automation using xlwings. This server provides comprehensive Excel file manipulation capabilities through a session-based architecture, designed for high-performance and reliable Excel operations.

๐Ÿš€ Features

Core Capabilities

  • Session-based Architecture: Persistent Excel workbook sessions for optimal performance

  • Comprehensive Excel Operations: Full support for data manipulation, formulas, formatting, and visualization

  • Thread-safe Operations: Concurrent access with per-session locking

  • Automatic Resource Management: TTL-based session cleanup and LRU eviction policies

  • Zero-Error Design: Katherine Johnson principle compliance with comprehensive error handling

Excel Operations

  • Workbook Management: Open, create, list, and close Excel workbooks

  • Worksheet Operations: Create, copy, rename, and delete worksheets

  • Data Manipulation: Read, write, and modify Excel data with full type support

  • Formula Support: Apply and validate Excel formulas with syntax checking

  • Advanced Formatting: Cell styling, conditional formatting, and range formatting

  • Visualization: Chart creation with multiple chart types

  • Table Operations: Native Excel table creation and management

  • Range Operations: Cell merging, copying, and deletion

๐Ÿ› ๏ธ Installation

Prerequisites

  • Python 3.10 or higher

  • Windows OS (required for xlwings COM integration)

  • Microsoft Excel installed

Using pip

pip install xlwings-mcp-server

From Source

git clone https://github.com/yourusername/xlwings-mcp-server.git cd xlwings-mcp-server pip install -e .

Using uv (Recommended)

uv add xlwings-mcp-server

โšก Quick Start

1. Basic Usage

Start the MCP server:

xlwings-mcp-server

Or run directly:

python -m xlwings_mcp

2. Session-based Workflow

# Example using MCP client import mcp # Open a workbook session session_result = client.call_tool("mcp__xlwings-mcp-server__open_workbook", { "filepath": "C:/path/to/your/file.xlsx", "visible": False, "read_only": False }) session_id = session_result["session_id"] # Write data client.call_tool("mcp__xlwings-mcp-server__write_data_to_excel", { "session_id": session_id, "sheet_name": "Sheet1", "data": [["Name", "Age", "Score"], ["Alice", 25, 95], ["Bob", 30, 87]] }) # Apply formulas client.call_tool("mcp__xlwings-mcp-server__apply_formula", { "session_id": session_id, "sheet_name": "Sheet1", "cell": "D2", "formula": "=B2+C2" }) # Create chart client.call_tool("mcp__xlwings-mcp-server__create_chart", { "session_id": session_id, "sheet_name": "Sheet1", "data_range": "A1:C3", "chart_type": "column", "target_cell": "E1" }) # Close session client.call_tool("mcp__xlwings-mcp-server__close_workbook", { "session_id": session_id })

๐Ÿ”ง Configuration

Environment Variables

# Session management EXCEL_MCP_SESSION_TTL=600 # Session TTL in seconds (default: 600) EXCEL_MCP_MAX_SESSIONS=8 # Maximum concurrent sessions (default: 8) EXCEL_MCP_DEBUG_LOG=1 # Enable debug logging (default: 0) # Excel settings EXCEL_MCP_VISIBLE=false # Show Excel windows (default: false) EXCEL_MCP_CALC_MODE=automatic # Calculation mode (default: automatic)

MCP Configuration (.mcp.json)

{ "name": "xlwings-mcp-server", "version": "1.0.0", "transport": { "type": "stdio" }, "tools": { "prefix": "mcp__xlwings-mcp-server__" } }

๐Ÿ“š API Reference

Session Management

  • open_workbook(filepath, visible=False, read_only=False): Create new session

  • close_workbook(session_id): Close session and save workbook

  • list_workbooks(): List active sessions

  • force_close_workbook_by_path(filepath): Force close by file path

Data Operations

  • write_data_to_excel(session_id, sheet_name, data, start_cell=None)

  • read_data_from_excel(session_id, sheet_name, start_cell=None, end_cell=None)

  • apply_formula(session_id, sheet_name, cell, formula)

  • validate_formula_syntax(session_id, sheet_name, cell, formula)

Worksheet Management

  • create_worksheet(session_id, sheet_name)

  • copy_worksheet(session_id, source_sheet, target_sheet)

  • rename_worksheet(session_id, old_name, new_name)

  • delete_worksheet(session_id, sheet_name)

Formatting & Visualization

  • format_range(session_id, sheet_name, start_cell, **formatting_options)

  • create_chart(session_id, sheet_name, data_range, chart_type, target_cell)

  • create_table(session_id, sheet_name, data_range, table_name=None)

Range Operations

  • merge_cells(session_id, sheet_name, start_cell, end_cell)

  • unmerge_cells(session_id, sheet_name, start_cell, end_cell)

  • copy_range(session_id, sheet_name, source_start, source_end, target_start)

  • delete_range(session_id, sheet_name, start_cell, end_cell)

๐Ÿ—๏ธ Architecture

Session-based Design

The server implements a sophisticated session management system:

  • ExcelSessionManager: Singleton pattern managing all Excel sessions

  • Per-session Isolation: Each session has independent Excel Application instance

  • Thread Safety: RLock per session preventing concurrent access issues

  • Resource Management: Automatic cleanup with TTL and LRU policies

  • Error Recovery: Comprehensive error handling and session recovery

Performance Optimizations

  • Session Reuse: Eliminates Excel restart overhead between operations

  • Connection Pooling: Efficient COM object management

  • Batch Operations: Optimized for multiple operations on same workbook

  • Memory Management: Proactive cleanup of Excel processes

๐Ÿงช Testing

Run Tests

# Run all tests python -m pytest test/ # Run specific test categories python -m pytest test/test_session.py # Session management python -m pytest test/test_functions.py # MCP function tests python -m pytest test/test_integration.py # Integration tests

Test Coverage

The project maintains 100% test coverage for:

  • All MCP tool functions (17 functions tested)

  • Session lifecycle management

  • Error handling and recovery

  • Performance benchmarks

๐Ÿ”’ Security Considerations

  • File System Access: Server operates within specified directory permissions

  • Excel Process Isolation: Each session runs in separate Excel instance

  • Resource Limits: Configurable session limits prevent resource exhaustion

  • Input Validation: All inputs validated before Excel API calls

  • Safe Defaults: Read-only mode available, invisible Excel instances by default

๐Ÿค Contributing

  1. Fork the repository

  2. Create a feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

Development Setup

git clone https://github.com/yourusername/xlwings-mcp-server.git cd xlwings-mcp-server uv venv uv sync uv run python -m xlwings_mcp

๐Ÿ“ Changelog

See CHANGELOG.md for detailed version history.

๐Ÿ› Troubleshooting

Common Issues

Excel COM Error: Ensure Excel is properly installed and not running in safe mode

# Check Excel installation excel --version

Session Not Found: Verify session hasn't expired (default TTL: 10 minutes)

# List active sessions client.call_tool("mcp__xlwings-mcp-server__list_workbooks")

Permission Denied: Run with appropriate file system permissions

# Windows: Run as administrator if needed

Debug Mode

Enable detailed logging:

export EXCEL_MCP_DEBUG_LOG=1 xlwings-mcp-server

๐Ÿ“„ License

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

๐Ÿ™ Acknowledgments

  • xlwings - Excellent Python-Excel integration library

  • Model Context Protocol - Standardized AI-tool communication

  • Claude Code - Development assistance

  • Katherine Johnson - Inspiration for zero-error engineering principles

๐Ÿ“ž Support


Made with โค๏ธ for the Excel automation community

Related MCP Servers

  • A
    security
    A
    license
    A
    quality
    Provides Excel file manipulation capabilities. This server enables workbook creation, data manipulation, formatting, and advanced Excel features.
    Last updated -
    25
    2,456
    Python
    MIT License
    • Linux
    • Apple
  • A
    security
    A
    license
    A
    quality
    A Model Context Protocol server that enables AI assistants to read from and write to Microsoft Excel files, supporting formats like xlsx, xlsm, xltx, and xltm.
    Last updated -
    6
    1,642
    537
    MIT License
    • Linux
    • Apple
  • A
    security
    A
    license
    A
    quality
    Enables seamless reading, writing, and analyzing of Excel files through Model Context Protocol, with features for worksheet management, structure analysis, and automated caching.
    Last updated -
    8
    99
    41
    MIT License
    • Linux
    • Apple
  • -
    security
    A
    license
    -
    quality
    Provides Excel file manipulation capabilities without requiring Microsoft Excel installation, enabling workbook creation, data manipulation, formatting, and advanced Excel features.
    Last updated -
    7
    MIT License
    • Linux
    • Apple

View all related MCP servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hyunjae-labs/xlwings-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server