nikhilwoodruff/xlsx

mcp-xlsx

MCP server for editing XLSX files, providing tools to read, write, format, and manage Excel spreadsheets.

Quick start (Claude Code)

Run the below from your user directory.

git clone https://github.com/nikhilwoodruff/xlsx && cd xlsx && uv pip install -e . && claude mcp add --transport stdio xlsx -- uv run mcp-xlsx

Installation

uv pip install -e .

Usage

With Claude Code

Add the MCP server using the CLI:

claude mcp add --transport stdio xlsx -- uv run mcp-xlsx

Or create a .mcp.json file in your project:

{
  "mcpServers": {
    "xlsx": {
      "command": "uv",
      "args": ["run", "mcp-xlsx"]
    }
  }
}

With Claude Desktop

Add to your Claude Desktop config (e.g., ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "xlsx": {
      "command": "uv",
      "args": ["run", "mcp-xlsx"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "xlsx": {
      "command": "mcp-xlsx"
    }
  }
}

Available tools

read_xlsx

Read data from an XLSX file.

Parameters:

• file_path (required): Path to the XLSX file
• sheet_name (optional): Sheet name (defaults to active sheet)
• range (optional): Cell range to read (e.g., 'A1:C10'). If not specified, reads entire sheet

write_xlsx

Write data to an XLSX file. Creates file if it doesn't exist.

Parameters:

• file_path (required): Path to the XLSX file
• data (required): 2D array of data to write (rows and columns)
• sheet_name (optional): Sheet name (creates if doesn't exist)
• start_cell (optional): Starting cell (e.g., 'A1'). Defaults to A1

update_cell

Update a specific cell value.

Parameters:

• file_path (required): Path to the XLSX file
• cell (required): Cell reference (e.g., 'A1', 'B5')
• value (required): Value to set (string, number, or boolean)
• sheet_name (optional): Sheet name

format_cell

Format a cell or range with styling options.

Parameters:

• file_path (required): Path to the XLSX file
• cell_range (required): Cell or range (e.g., 'A1' or 'A1:C10')
• sheet_name (optional): Sheet name
• bold (optional): Make text bold
• italic (optional): Make text italic
• font_size (optional): Font size in points
• font_color (optional): Font color in hex (e.g., 'FF0000' for red)
• bg_color (optional): Background color in hex (e.g., 'FFFF00' for yellow)
• alignment (optional): Text alignment: 'left', 'center', 'right'

list_sheets

List all sheet names in an XLSX file.

Parameters:

• file_path (required): Path to the XLSX file

create_sheet

Create a new sheet in an XLSX file.

Parameters:

• file_path (required): Path to the XLSX file
• sheet_name (required): Name for the new sheet

delete_sheet

Delete a sheet from an XLSX file.

Parameters:

• file_path (required): Path to the XLSX file
• sheet_name (required): Name of the sheet to delete

Example usage

Once configured in Claude Code or Claude Desktop, you can ask Claude to:

• "Read the data from sales.xlsx"
• "Create a new spreadsheet called budget.xlsx with these columns: Month, Income, Expenses"
• "Update cell B2 in report.xlsx to 1000"
• "Format cells A1:D1 as bold with yellow background"
• "List all sheets in workbook.xlsx"

Development

Install dependencies:

uv pip install -e .

Format code:

ruff format src/

Lint code:

ruff check src/