excel-mcp-server

For local use, run the server using the stdio transport. This is the simplest method for local AI agents. When using stdio, you do not need to set the EXCEL_FILES_PATH environment variable, as the file path is provided directly with each tool call.

uvx excel-mcp-server stdio

For remote connections, use the streamable-http transport. This is the recommended method for remote services. When using this transport, you must set the EXCEL_FILES_PATH environment variable on the server side to define the directory where Excel files are stored.

uvx excel-mcp-server streamable-http

To connect to a remote Excel MCP server using Streamable HTTP, use the following configuration in your client settings, pointing to the server's /mcp endpoint:

{
   "mcpServers": {
      "excel": {
         "url": "http://localhost:8000/mcp",
      }
   }
}

When using SSE or Streamable HTTP transports, you must configure the following environment variables on the server:

• EXCEL_FILES_PATH: The directory where the server reads and writes Excel files. Defaults to ./excel_files.
  • Important: When using these transports, tool filepath values must be relative to this directory (e.g., reports/q1.xlsx). Absolute paths and directory traversal are rejected.
• FASTMCP_PORT: The port the server listens on. Defaults to 8017.

Examples

Linux/macOS:

EXCEL_FILES_PATH=/path/to/excel_files FASTMCP_PORT=8007 uvx excel-mcp-server streamable-http

Windows PowerShell:

$env:EXCEL_FILES_PATH="E:\MyExcelFiles"
$env:FASTMCP_PORT="8007"
uvx excel-mcp-server streamable-http

To use the Excel MCP server locally with an MCP-compatible client (like Cursor), add the following configuration to your mcpServers settings:

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

Note: SSE (Server-Sent Events) transport is deprecated. If you must use it, point your client to the server's /sse endpoint:

{
   "mcpServers": {
      "excel": {
         "url": "http://localhost:8000/sse",
      }
   }
}

The Excel MCP server can be executed using three different transport methods depending on your connection requirements:

1. Stdio Transport: Best for local use. In this mode, file paths provided to tools must be absolute paths.
2. SSE Transport (Deprecated): Uses Server-Sent Events. Requires setting the EXCEL_FILES_PATH environment variable to a directory where Excel files are stored.
3. Streamable HTTP Transport (Recommended): Recommended for remote connections. Requires setting the EXCEL_FILES_PATH environment variable.

When using SSE or Streamable HTTP, file paths provided to tools are treated as relative to the directory specified in EXCEL_FILES_PATH.

Use these tools to work with Excel formulas:

• apply_formula(filepath: str, sheet_name: str, cell: str, formula: str): Applies a specific Excel formula to a target cell.
• validate_formula_syntax(filepath: str, sheet_name: str, cell: str, formula: str): Validates the syntax of an Excel formula without actually applying it to the sheet.

Use the following tools to manage workbook files and their constituent worksheets:

• create_workbook(filepath: str): Creates a new Excel workbook at the specified path.
• create_worksheet(filepath: str, sheet_name: str): Adds a new worksheet to an existing workbook.
• get_workbook_metadata(filepath: str, include_ranges: bool = False): Retrieves metadata about the workbook, including sheets and ranges. Set include_ranges to True to include range information.
• copy_worksheet(filepath: str, source_sheet: str, target_sheet: str): Copies a worksheet within the same workbook.
• rename_worksheet(filepath: str, old_name: str, new_name: str): Renames an existing worksheet.
• delete_worksheet(filepath: str, sheet_name: str): Deletes a worksheet from the workbook.

Apply visual styles and structural changes to cells:

• format_range(filepath: str, sheet_name: str, start_cell: str, end_cell: str = None, ...): Applies various formatting options including bold, italic, underline, font_size, font_color, bg_color, border_style, border_color, number_format, alignment, wrap_text, merge_cells, protection, and conditional_format.
• merge_cells(filepath: str, sheet_name: str, start_cell: str, end_cell: str): Merges a range of cells.
• unmerge_cells(filepath: str, sheet_name: str, start_cell: str, end_cell: str): Unmerges a previously merged range.
• get_merged_cells(filepath: str, sheet_name: str): Returns a representation of all merged cells in a worksheet.

Generate analytical objects in worksheets:

• create_chart(filepath: str, sheet_name: str, data_range: str, chart_type: str, target_cell: str, title: str = "", x_axis: str = "", y_axis: str = ""): Creates a chart (types: line, bar, pie, scatter, area) from a data range.
• create_pivot_table(filepath: str, sheet_name: str, data_range: str, target_cell: str, rows: List[str], values: List[str], columns: List[str] = None, agg_func: str = "mean"): Creates a pivot table. Supported agg_func values are sum, count, average, max, min.

Convert data ranges into native Excel tables:

• create_table(filepath: str, sheet_name: str, data_range: str, table_name: str = None, table_style: str = "TableStyleMedium9"): Creates a native Excel table from a specified range.