Xlsm MCP Server

🚀 📊 MCP Server for Excel Files with Macros (.xlsm)

This server implements the Model Context Protocol (MCP) for handling Excel files with macros (.xlsm). It uses the stdio protocol for communication, enabling seamless integration with MCP clients such as Claude Desktop, Cursor, or Windsurf.

Author: Orlando Ospino (orlando2019)

🚀 Quick Start

The MCP (Model Context Protocol) server for Excel files with macros allows language models to interact with external Excel tools. With this server, Claude and other AI assistants can naturally handle Excel files with macros, expanding their capabilities in data analysis and office automation tasks.

✨ Features

• Create and manipulate Excel files with macros (.xlsm).
• Read and write worksheet data.
• Manage worksheets (create, delete, rename).
• List and obtain information about VBA macros.
• Apply cell range formatting.
• Compatible with Python 3.10+.
• Easily integrate into virtual environments and modern MCP clients.

📦 Installation

Using pip

pip install xlsm-mcp-server

Using uv (Recommended)

uv venv
.venv\Scripts\activate
uv pip install -r requirements.txt

💻 Usage Examples

Basic Usage

Run the server directly:

python -m xlsm_mcp

Or in a virtual environment:

.venv\Scripts\python.exe -m xlsm_mcp

Configuration for Claude Desktop, Cursor, or Windsurf

Add the following to your configuration file (e.g., settings.json):

"mcpServers": {
  "xlsm": {
    "command": "python",
    "args": ["-m", "xlsm_mcp"],
    "transport": "stdio"
  }
}

• You can omit "transport": "stdio" in some clients, but it is recommended to keep it for optimal compatibility.
• If you are using a virtual environment, replace "python" with the actual path to your Python executable.

Advanced Usage

You can add custom parameters in the "args" section to adjust the server behavior as needed, for example:

"args": ["-m", "xlsm_mcp", "--log-level", "DEBUG"]

Available Tools

• read_data_from_excel: Read data from an Excel file.
• write_data_to_excel: Write data to an Excel worksheet.
• create_new_workbook: Create a new Excel file with macro support.
• create_new_worksheet: Add a new worksheet to an existing file.
• get_workbook_metadata: Get file metadata, including macro-related information.
• list_macros_in_workbook: List all macros in a file.
• get_macro_details: Get detailed information about a specific macro.
• format_cell_range: Apply formatting to a cell range.

Code Examples

Read data from an Excel file

# Example code: Read data from an Excel file
import xlsm_mcp as mcp
mcp.read_data_from_excel("example.xlsx")

Write data to an Excel worksheet

# Example code: Write data to an Excel worksheet
import xlsm_mcp as mcp
data = {
    "A": [1, 2, 3],
    "B": ["a", "b", "c"]
}
mcp.write_data_to_excel("example.xlsx", data)

📚 Documentation

Important Notes

• Ensure you have installed Python 3.10 or a higher version.
• When using a virtual environment, activate it before running the server.
• For complex macro files, performance issues may occur. It is recommended to test and optimize accordingly.

If you have any questions, please feel free to contact the author.