Skip to main content
Glama

xlwings Excel MCP Server

by hyunjae-labs
GitHub
Python
3
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

xlwings-mcp-server

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

Deploy Server
A
security – no known vulnerabilities
F
license - not found
A
quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

Enables Excel file manipulation through Microsoft's official COM automation interface using xlwings, designed for corporate environments where security policies prevent direct file access. Provides 25 tools for workbook operations, data manipulation, formatting, charts, pivot tables, and worksheet management through native Excel integration.

  1. 🚀 Features
    1. Core Capabilities
    2. Excel Operations
  2. 🛠️ Installation
    1. Prerequisites
    2. Using pip
    3. From Source
    4. Using uv (Recommended)
  3. ⚡ Quick Start
    1. 1. Basic Usage
    2. 2. Session-based Workflow
  4. 🔧 Configuration
    1. Environment Variables
    2. MCP Configuration (.mcp.json)
  5. 📚 API Reference
    1. Session Management
    2. Data Operations
    3. Worksheet Management
    4. Formatting & Visualization
    5. Range Operations
  6. 🏗️ Architecture
    1. Session-based Design
    2. Performance Optimizations
  7. 🧪 Testing
    1. Run Tests
    2. Test Coverage
  8. 🔒 Security Considerations
    1. 🤝 Contributing
      1. Development Setup
    2. 📝 Changelog
      1. 🐛 Troubleshooting
        1. Common Issues
        2. Debug Mode
      2. 📄 License
        1. 🙏 Acknowledgments
          1. 📞 Support

            Related MCP Servers

            • Excel MCP Server

              haris-musa
              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,269
              Python
              MIT License
              • Linux
              • Apple

            • Excel MCP Server

              negokaz
              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,627
              497
              MIT License
              • Linux
              • Apple

            • Excel MCP Server

              zhiwei5576
              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
              128
              41
              MIT License
              • Linux
              • Apple

            • Excel MCP Server

              fish0710
              -
              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 -
              6
              MIT License
              • Linux
              • Apple

            View all related MCP servers

            New 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