The xlwings Excel MCP Server is a session-based automation tool that enables comprehensive Excel file manipulation through the Model Context Protocol.
Session & Workbook Management: Open, close, list, and manage persistent workbook sessions with automatic cleanup (TTL, LRU); create new workbooks and force-close by file path.
Data Operations: Read data from cells/ranges (including metadata and validation rules) and write various data types to worksheets.
Formula Management: Apply Excel formulas to cells with verification and validate formula syntax without execution.
Worksheet Operations: Create, copy, rename, delete worksheets; insert or delete rows and columns.
Formatting & Styling: Apply extensive cell formatting including bold, italic, underline, font size, colors, alignment, borders, number formats, conditional formatting, and text wrapping.
Range Operations: Merge/unmerge cells, copy data between ranges, delete ranges, and validate Excel ranges.
Visualization: Create various chart types with customization options (title, axes) and generate pivot tables with configurable rows, columns, values, and aggregation functions.
Table Operations: Create and manage native Excel tables from data ranges.
Metadata Retrieval: Get workbook metadata (sheets, ranges) and detailed data validation information.
Provides comprehensive Excel file manipulation through xlwings Python library, enabling creation, editing, and management of Excel workbooks, worksheets, data, formulas, charts, and pivot tables via COM automation
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@xlwings Excel MCP Server add a column chart for sales data in Q1 sheet"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
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
Related MCP server: Excel MCP Server
Python 3.10 or higher
Windows OS (required for xlwings COM integration)
Microsoft Excel installed
pip install xlwings-mcp-servergit clone https://github.com/yourusername/xlwings-mcp-server.git
cd xlwings-mcp-server
pip install -e .uv add xlwings-mcp-serverStart the MCP server:
xlwings-mcp-serverOr run directly:
python -m xlwings_mcp# 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
})# 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){
"name": "xlwings-mcp-server",
"version": "1.0.0",
"transport": {
"type": "stdio"
},
"tools": {
"prefix": "mcp__xlwings-mcp-server__"
}
}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
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)
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)
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)
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)
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
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
# 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 testsThe project maintains 100% test coverage for:
All MCP tool functions (17 functions tested)
Session lifecycle management
Error handling and recovery
Performance benchmarks
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
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request
git clone https://github.com/yourusername/xlwings-mcp-server.git
cd xlwings-mcp-server
uv venv
uv sync
uv run python -m xlwings_mcpSee CHANGELOG.md for detailed version history.
Excel COM Error: Ensure Excel is properly installed and not running in safe mode
# Check Excel installation
excel --versionSession 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 neededEnable detailed logging:
export EXCEL_MCP_DEBUG_LOG=1
xlwings-mcp-serverThis project is licensed under the MIT License - see the LICENSE file for details.
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
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: haris.musa@outlook.com
Made with โค๏ธ for the Excel automation community
Apply Excel formula to cell.
Args:
session_id: Session ID from open_workbook (required)
sheet_name: Name of worksheet
cell: Cell address (e.g., "A1")
formula: Excel formula to apply
Inputs: session_id (required), sheet_name (required), cell (required), formula (required). Returns: result
Close a workbook session.
Args:
session_id: Session ID from open_workbook
save: Whether to save changes (default: True)
Returns:
Success message
Inputs: session_id (required), save. Returns: result
Copy a range of cells to another location.
Args:
sheet_name: Name of source worksheet
source_start: Starting cell of source range
source_end: Ending cell of source range
target_start: Starting cell of target range
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
target_sheet: Target worksheet (optional, uses source sheet if not provided)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), source_start (required), source_end (required), target_start (required), +3 more. Returns: result
Copy worksheet within workbook.
Args:
session_id: Session ID from open_workbook (required)
source_sheet: Name of the source worksheet
target_sheet: Name of the target worksheet
Inputs: session_id (required), source_sheet (required), target_sheet (required). Returns: result
Create chart in worksheet.
Args:
sheet_name: Name of worksheet
data_range: Data range for chart
chart_type: Type of chart
target_cell: Cell where chart will be placed
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
title: Chart title (optional)
x_axis: X-axis label (optional)
y_axis: Y-axis label (optional)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), data_range (required), chart_type (required), target_cell (required), +5 more. Returns: result
Create pivot table in worksheet.
Args:
sheet_name: Name of worksheet containing source data
data_range: Source data range (e.g., "A1:E100" or "Sheet2!A1:E100")
rows: Field names for row labels
values: Field names for values
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
columns: Field names for column labels (optional)
agg_func: Aggregation function (sum, count, average, max, min)
target_sheet: Target sheet for pivot table (optional, auto-created if not exists)
target_cell: Target cell for pivot table (optional, finds empty area if not provided)
pivot_name: Custom name for pivot table (optional, auto-generated if not provided)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), data_range (required), rows (required), values (required), +7 more. Returns: result
Creates a native Excel table from a specified range of data.
Args:
sheet_name: Name of worksheet
data_range: Range of data to create table from
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
table_name: Name for the table (optional)
table_style: Style for the table (optional)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), data_range (required), session_id, filepath, +2 more. Returns: result
Create new Excel workbook.
Args:
session_id: Session ID for creating workbook in existing session (optional)
filepath: Path to create new Excel file (legacy, deprecated)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: session_id, filepath. Returns: result
Create new worksheet in workbook.
Args:
session_id: Session ID from open_workbook (required)
sheet_name: Name of the new worksheet
Inputs: session_id (required), sheet_name (required). Returns: result
Delete a range of cells and shift remaining cells.
Args:
sheet_name: Name of worksheet
start_cell: Starting cell
end_cell: Ending cell
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
shift_direction: Direction to shift cells ("up" or "left")
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), start_cell (required), end_cell (required), session_id, +2 more. Returns: result
Delete one or more columns starting at the specified column.
Args:
sheet_name: Name of worksheet
start_col: Column number to start deleting from
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
count: Number of columns to delete
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), start_col (required), session_id, filepath, +1 more. Returns: result
Delete one or more rows starting at the specified row.
Args:
sheet_name: Name of worksheet
start_row: Row number to start deleting from
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
count: Number of rows to delete
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), start_row (required), session_id, filepath, +1 more. Returns: result
Delete worksheet from workbook.
Args:
session_id: Session ID from open_workbook (required)
sheet_name: Name of the worksheet to delete
Inputs: session_id (required), sheet_name (required). Returns: result
Force close a specific workbook by file path (without saving).
Args:
filepath: Path to the workbook to force close
Returns:
Dictionary with 'closed' (bool) and 'message' (str)
Inputs: filepath (required). Returns: result
Apply formatting to a range of cells.
Args:
sheet_name: Name of worksheet
start_cell: Starting cell
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
end_cell: Ending cell (optional)
bold: Apply bold formatting
italic: Apply italic formatting
underline: Apply underline formatting
font_size: Font size
font_color: Font color
bg_color: Background color
border_style: Border style
border_color: Border color
number_format: Number format
alignment: Text alignment
wrap_text: Enable text wrapping
merge_cells: Merge cells in range
protection: Cell protection settings (optional)
conditional_format: Conditional formatting settings (optional)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), start_cell (required), session_id, filepath, +15 more. Returns: result
Get all data validation rules in a worksheet.
This tool helps identify which cell ranges have validation rules
and what types of validation are applied.
Args:
sheet_name: Name of worksheet
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
Note: Use session_id for better performance. filepath parameter is deprecated.
Returns:
JSON string containing all validation rules in the worksheet
Inputs: sheet_name (required), session_id, filepath. Returns: result
Get merged cells in a worksheet.
Args:
sheet_name: Name of worksheet
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), session_id, filepath. Returns: result
Get metadata about workbook including sheets, ranges, etc.
Args:
session_id: Session ID from open_workbook (required)
include_ranges: Whether to include range information
Inputs: session_id (required), include_ranges. Returns: result
Insert one or more columns starting at the specified column.
Args:
sheet_name: Name of worksheet
start_col: Column number to start inserting at
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
count: Number of columns to insert
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), start_col (required), session_id, filepath, +1 more. Returns: result
Insert one or more rows starting at the specified row.
Args:
sheet_name: Name of worksheet
start_row: Row number to start inserting at
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
count: Number of rows to insert
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), start_row (required), session_id, filepath, +1 more. Returns: result
List all open workbook sessions.
Returns:
List of session information dictionaries
Inputs: no named parameters. Returns: result
Merge a range of cells.
Args:
sheet_name: Name of worksheet
start_cell: Starting cell
end_cell: Ending cell
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), start_cell (required), end_cell (required), session_id, +1 more. Returns: result
Open an Excel workbook and create a session.
Args:
filepath: Path to Excel file
visible: Whether to show Excel window (default: False)
read_only: Whether to open in read-only mode (default: False)
Returns:
Dictionary with session_id, filepath, visible, read_only, and sheets
Inputs: filepath (required), visible, read_only. Returns: result
Read data from Excel worksheet with cell metadata including validation rules.
Args:
session_id: Session ID from open_workbook (required)
sheet_name: Name of worksheet
start_cell: Starting cell (default A1)
end_cell: Ending cell (optional, auto-expands if not provided)
preview_only: Whether to return preview only
Inputs: session_id (required), sheet_name (required), start_cell, end_cell, +1 more. Returns: result
Rename worksheet in workbook.
Args:
session_id: Session ID from open_workbook (required)
old_name: Current name of the worksheet
new_name: New name for the worksheet
Inputs: session_id (required), old_name (required), new_name (required). Returns: result
Unmerge a range of cells.
Args:
sheet_name: Name of worksheet
start_cell: Starting cell
end_cell: Ending cell
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), start_cell (required), end_cell (required), session_id, +1 more. Returns: result
Validate if a range exists and is properly formatted.
Args:
sheet_name: Name of worksheet
start_cell: Starting cell
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
end_cell: Ending cell (optional)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), start_cell (required), session_id, filepath, +1 more. Returns: result
Validate Excel formula syntax without applying it.
Args:
sheet_name: Name of worksheet
cell: Cell address (e.g., "A1")
formula: Excel formula to validate
session_id: Session ID from open_workbook (preferred)
filepath: Path to Excel file (legacy, deprecated)
Note: Use session_id for better performance. filepath parameter is deprecated.
Inputs: sheet_name (required), cell (required), formula (required), session_id, +1 more. Returns: result
Write data to Excel worksheet.
Excel formula will write to cell without any verification.
Args:
session_id: Session ID from open_workbook (required)
sheet_name: Name of worksheet to write to
data: List of lists containing data to write to the worksheet, sublists are assumed to be rows
start_cell: Cell to start writing to (optional, auto-finds appropriate location)
Inputs: session_id (required), sheet_name (required), data (required), start_cell. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
Scored across 29 tools
Most tools have distinct purposes targeting specific Excel operations like formulas, ranges, sheets, or charts, with clear boundaries. However, some overlap exists between 'delete_range' and 'delete_sheet_rows/columns', which could cause confusion about which to use for row/column deletion, and 'validate_excel_range' might be redundant with range validation implied in other tools.
Tool names follow a highly consistent verb_noun pattern throughout, such as 'apply_formula', 'close_workbook', 'copy_range', and 'create_chart'. The only minor deviation is 'force_close_workbook_by_path_tool', which still adheres to the pattern but includes extra descriptors, maintaining overall readability and predictability.
With 29 tools, the count is borderline high for an Excel server, potentially overwhelming for agents. While Excel is a complex domain, the set includes some specialized tools like 'get_merged_cells' and 'validate_formula_syntax' that might be less frequently used, suggesting the surface could be more streamlined without losing core functionality.
The tool set provides comprehensive coverage for Excel operations, including workbook management (open, close, create), sheet operations (create, delete, rename), data manipulation (read, write, copy, delete), formatting, charts, pivot tables, and validation. There are no obvious gaps; agents can perform full CRUD and lifecycle tasks for Excel files seamlessly.
File tools for your AI chat: PDF tables to Excel, merge PDFs, images to PDF, fill PDF forms.
Convert, create and edit Word, PowerPoint, Excel and PDF documents from any AI agent.
Excel analytics: inspect, query (JSON rows), charts, and JSON-to-xlsx workbook writing.
Let AI agents read, check and edit Excel models. Open a workbook or drop in one MCP config. Either way: typed cells, a formula dependency graph, and a verification certificate. Deterministic โ no OCR, no model guessing at your numbers.
