# Excel MCP Server

This project is an MCP (Model Context Protocol) server for AI models that can read Excel files and return their contents as CSV text per sheet.

## What it does

The server exposes a tool that reads an Excel file from disk and returns an object where each key is the name of a sheet and each value is the content of that sheet in CSV format.

## Requirements

- Node.js
- npm, pnpm (recommended), or any compatible Node.js package manager

## Installation

- Install the dependencies with:

```bash
npm install
```

- Or with pnpm:

```bash
pnpm install
```

For security reasons, the pnpm package manager is recommended. You can configure it with the following command before installing any dependencies:

```bash
pnpm config set minimum-release-age 1440 --global
```

This adds a layer of security against supply chain attacks.

- Or install dependencies with your favorite Node.js package manager.

## Usage with MCP clients

This server is intended to be started by MCP-compatible clients. You generally do not need to run it manually. Below are example client configurations (replace /path/to/... with the actual path on your system).

- Continue (VSCode extension) — example `config.yaml`:

```yaml
mcpServers:
    - name: excel MCP server
      command: npx
      args:
          - -y
          - node
          - /path/to/mcp_servers/excel/main.js
      env: {}
```

- Claude (desktop) — example `claude_desktop_config.json`:

```json
{
    "mcpServers": {
        "excel": {
            "command": "npx",
            "args": ["-y", "node", "/path/to/mcp_servers/excel/main.js"]
        }
    }
}
```

- GitHub Copilot (VSCode). Press Ctrl+Shift+P (Windows or Linux) or Cmd+Shift+P (Mac) to open the Command Palette. Execute the MCP: Open User Configuration command. This creates a clean `mcp.json` in your global user profile directory. Edit the `mcp.json` file and place the following:

```json
{
    "servers": {
        "excel": {
            "command": "npx",
            "args": ["-y", "node", "/path/to/mcp_servers/excel/main.js"]
        }
    }
}
```

- Generic MCP client (command line):

```bash
npx -y node /path/to/mcp_servers/excel/main.js
```

## Tool exposed

The server exposes the following MCP tool:

- read-excel-file
    - Parameters:
        - file_absolute_path: the absolute path to the Excel file to read

## Example

If the Excel file contains two sheets, the tool may return a response like:

```json
{
    "success": true,
    "result": {
        "Sheet1": "name,age\nAna,30\nLuis,25",
        "Sheet2": "city,country\nMadrid,Spain\nLima,Peru"
    }
}
```

## Notes

- Check the documentation of the MCP client you use for the exact configuration key names; the examples above are common templates.
- When chatting with the AI, make sure to provide the absolute path of Excel file.