Skip to main content
Glama
mcp-server-xlwings

mcp-server-xlwings

by geniuskey

mcp-server-xlwings

MCP server for Excel automation via xlwings COM. Works with DRM-protected files.

PyPI License: MIT Python 3.10+

Why xlwings?

Libraries like openpyxl or pandas read .xlsx files directly from disk. This fails when:

  • DRM / file-level encryption is applied (common in enterprise environments)

  • You need to interact with a live Excel session (formulas, macros, add-ins)

  • Files are locked by another process

mcp-server-xlwings uses COM automation to talk to the running Excel process, so it can read and write any file that Excel itself can open -- including DRM-protected documents.

xlwings-exclusive capabilities

These features are impossible with file-based libraries like openpyxl:

  • Read the user's current selection -- see exactly what the user is looking at

  • Get the active workbook -- no need to specify a file path

  • Run VBA macros -- execute existing macros and get their return values

  • Live formula results -- set a formula and get the calculated value immediately

  • Force recalculation -- trigger Excel to recalculate all formulas

Related MCP server: xlwings Excel MCP Server

Installation

uvx mcp-server-xlwings

With pip

pip install mcp-server-xlwings

Configuration

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "xlwings": {
      "command": "uvx",
      "args": ["mcp-server-xlwings"]
    }
  }
}

Claude Code

claude mcp add xlwings -- uvx mcp-server-xlwings

Roo Code (VS Code)

Add to Roo Code MCP settings or create <project-root>/.roo/mcp.json:

{
  "mcpServers": {
    "xlwings": {
      "command": "uvx",
      "args": ["mcp-server-xlwings"]
    }
  }
}

Cursor

Add to %USERPROFILE%\.cursor\mcp.json:

{
  "mcpServers": {
    "xlwings": {
      "command": "uvx",
      "args": ["mcp-server-xlwings"]
    }
  }
}

Windsurf

Add to %USERPROFILE%\.codeium\windsurf\mcp_config.json:

{
  "mcpServers": {
    "xlwings": {
      "command": "uvx",
      "args": ["mcp-server-xlwings"]
    }
  }
}

Continue (VS Code)

Add to ~/.continue/config.yaml:

mcpServers:
  - name: xlwings
    command: uvx
    args:
      - mcp-server-xlwings

Available Tools (11)

All tools default to the active workbook when workbook is omitted.

Tool

Description

get_active_workbook

Get active workbook info, sheets, and current selection with data

manage_workbooks

List, open, save, close, or recalculate workbooks

read_data

Read a range with merge_info, header_row, sheet="*" batch read, and detail mode

write_data

Write a 2D array (data) or a single-cell formula (formula)

manage_sheets

List, add, delete, rename, copy, activate sheets. Insert/delete rows and columns

find_replace

Search for text, optionally replace it

format_range

Apply formatting (bold, italic, color, borders, alignment, number format, etc.)

run_macro

Execute a VBA macro and get its return value

get_formulas

Get all formulas in a range with optional calculated values

get_cell_styles

Get formatting/style info (bold, colors, borders, etc.) for cells in a range

get_objects

List charts, images, and shapes on a sheet

Examples

See what the user is working on

"What's in the spreadsheet I have open?"

The agent calls get_active_workbook() to get the workbook name, sheets, and selection data, then read_data() to fetch the full sheet.

Summarize selected data

"Summarize the data I've selected"

The agent calls get_active_workbook() -- the response includes the selection data directly.

Run a macro

"Run the UpdateReport macro"

The agent calls run_macro(macro_name="UpdateReport") and returns the result.

Build a summary row

"Add a SUM formula in C10 that totals C2:C9"

The agent calls write_data(start_cell="C10", formula="=SUM(C2:C9)") and gets back the calculated value.

Format a header row

"Make row 1 bold and centered with a yellow background"

The agent calls format_range(cell_range="A1:D1", bold=true, alignment="center", bg_color="#FFFF00").

Read all sheets at once

"Give me a summary of every sheet"

The agent calls read_data(sheet="*") -- returns all sheet summaries in a single call.

Read merged cells properly

"Read B6:C20 and fill in merged cell values"

The agent calls read_data(cell_range="B6:C20", merge_info=true). Merged cells return the parent value instead of null.

Find all formulas

"Show me all formulas in this sheet"

The agent calls get_formulas(cell_range="A1:Z100", values_too=true) and gets every formula with its calculated value.

Insert rows

"Insert 3 blank rows at row 5"

The agent calls manage_sheets(action="insert_rows", position=5, count=3).

Requirements

  • Windows (Excel COM automation is Windows-only)

  • Microsoft Excel installed

  • Python 3.10+

License

MIT

Available Tools

11 tools
find_replaceA

Search for text in a sheet, optionally replacing it.

Args: find: Text to search for. workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet. replace: Replacement text. If omitted, search only. match_case: Case-sensitive matching.

Inputs: find (required), workbook, sheet, replace, +1 more.

format_rangeB
Destructive

Apply formatting to a cell range.

Args: cell_range: Range like 'A1:D10'. workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet. bold: Set bold. italic: Set italic. underline: Set underline. font_size: Font size in points. font_color: Hex colour like '#FF0000'. bg_color: Background hex colour like '#FFFF00'. number_format: Excel format like '#,##0.00'. alignment: 'left', 'center', 'right', 'justify'. wrap_text: Enable text wrapping. border: Apply thin borders.

Inputs: cell_range (required), workbook, sheet, bold, +9 more.

get_active_workbookA
Read-only

Get the currently active workbook info including sheets, active sheet, and current selection address with its data.

Inputs: no named parameters.

get_cell_stylesA
Read-only

Get formatting/style info for cells in a range. Returns only cells with non-default styles. Useful for identifying headers, subtotals, and data roles by visual formatting.

Args: cell_range: Range like 'A1:D10'. workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet. properties: Filter specific properties (bold, italic, underline, font_name, font_size, font_color, bg_color, number_format, alignment, border).

Inputs: cell_range (required), workbook, sheet, properties.

get_formulasA
Read-only

Get all formulas in a range. Returns only cells that contain formulas.

Args: cell_range: Range like 'A1:U99'. workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet. values_too: Include calculated values alongside formulas.

Inputs: cell_range (required), workbook, sheet, values_too.

get_objectsA
Read-only

List charts, images, and shapes on a sheet.

Args: workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet.

Inputs: workbook, sheet.

manage_sheetsA
Destructive

Manage sheets and structure.

Args: action: One of 'list', 'add', 'delete', 'rename', 'copy', 'activate', 'insert_rows', 'delete_rows', 'insert_columns', 'delete_columns'. workbook: Workbook name or path. Defaults to active workbook. sheet: Target sheet name (required for delete/rename/copy/activate). new_name: New name (for rename; optional for add/copy). position: Row/column number (1-based) for insert/delete actions. count: Number of rows/columns to insert or delete.

Inputs: action (required), workbook, sheet, new_name, +2 more.

manage_workbooksA
Destructive

Manage Excel workbooks: list, open, save, close, or recalculate.

Args: action: One of 'list', 'open', 'save', 'close', 'recalculate'. workbook: Workbook name or path. Defaults to active workbook. filepath: For 'open': file path (use 'new' for blank). For 'save': Save As path. read_only: For 'open': open in read-only mode. save: For 'close': save before closing.

Inputs: action (required), workbook, filepath, read_only, +1 more.

read_dataA
Read-only

Read data from an Excel range. When cell_range is omitted, returns a sheet summary (used range address, total rows/columns, headers) WITHOUT reading all data -- call again with a specific cell_range to fetch the actual data. Set detail=True on a single cell to get formula, type, and formatting info. Use sheet="*" to batch-read all sheets in one call.

Args: workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet. Use '*' to read all sheets. cell_range: Range like 'A1:D10' or cell like 'B5'. Returns sheet summary if omitted. headers: Treat first row as column headers. detail: For single cells, include formula, type, number format, and font info. merge_info: Fill merged cells with the merge area's value instead of null. header_row: 1-based row number to use as headers (e.g. 3 means row 3 is headers).

Inputs: workbook, sheet, cell_range, headers, +3 more.

run_macroA
Destructive

Run a VBA macro in Excel and return its result.

Args: macro_name: Macro name (e.g. 'MyMacro' or 'Module1.MyMacro'). workbook: Workbook name. If omitted, Excel resolves globally. args: Optional arguments to pass to the macro.

Inputs: macro_name (required), workbook, args.

write_dataA
Destructive

Write data or a formula to Excel cells. Provide 'data' for a 2D array, or 'formula' for a single-cell formula.

Args: start_cell: Top-left cell (e.g. 'A1'). data: 2D list of values. Mutually exclusive with formula. formula: Excel formula like '=SUM(A1:A10)'. Mutually exclusive with data. workbook: Workbook name or path. Defaults to active workbook. sheet: Sheet name. Defaults to active sheet.

Inputs: start_cell (required), data, formula, workbook, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct operation: read, write, format, find/replace, manage sheets/workbooks, run macros, retrieve formulas/styles/objects, and get active workbook info. No overlapping purposes; descriptions clearly differentiate them.

    Naming Consistency5/5

    All tools follow the verb_noun pattern with underscores (e.g., find_replace, get_cell_styles). Verbs are imperative and consistent throughout, making the naming predictable and easy to understand.

    Tool Count5/5

    With 11 tools, the server covers core Excel interactions without excess. It provides enough functionality to automate common tasks without overwhelming the agent with too many choices.

    Completeness4/5

    The tool surface covers reading, writing, formatting, finding, managing structure, running macros, and inspecting styles/objects. Minor gaps exist, such as creating charts or pivot tables, but the set is sufficient for typical data manipulation and formatting workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      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.
      29
      9
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to read, write, format, and execute VBA macros in Microsoft Excel in real-time through the Model Context Protocol, connecting directly to an open Excel window via COM integration.
      -