# Clone the repository
git clone https://github.com/username/mcp-excel-server.git
cd mcp-excel-server

# Install with Poetry
poetry install

# Or with pip
pip install -e .

# For VBA macro support (requires Excel installed)
pip install -e ".[vba]"

# Copy environment template
cp .env.example .env

# Edit .env with your settings
# MCP_EXCEL_TRANSPORT=stdio
# MCP_EXCEL_CACHE_SIZE=5

# Using Poetry
poetry run python -m mcp_excel.server

# Or directly
python -m mcp_excel.server

{
  "mcpServers": {
    "excel": {
      "command": "python",
      "args": ["-m", "mcp_excel.server"],
      "cwd": "/path/to/mcp-excel-server"
    }
  }
}

{
  "mcpServers": {
    "excel": {
      "command": "python",
      "args": ["-m", "mcp_excel.server"],
      "cwd": "${workspaceFolder}"
    }
  }
}

{
  "mcpServers": {
    "excel": {
      "command": "python",
      "args": ["-m", "mcp_excel.server"],
      "env": {
        "MCP_EXCEL_TRANSPORT": "stdio"
      }
    }
  }
}

User: Read the sales data from C:/reports/Q1.xlsx

Agent calls:
1. describe_workbook(file_path="C:/reports/Q1.xlsx")
2. list_sheets(file_path="C:/reports/Q1.xlsx")
3. read_range(file_path="C:/reports/Q1.xlsx", sheet_name="Sales", range="A1:F100")

User: Create a monthly summary with totals

Agent calls:
1. create_sheet(file_path="report.xlsx", sheet_name="Summary")
2. write_cells(file_path="report.xlsx", sheet_name="Summary", range="A1:D1", values=[["Month", "Sales", "Cost", "Profit"]])
3. write_formula(file_path="report.xlsx", sheet_name="Summary", cell="D2", formula="=B2-C2")

User: Analyze customer demographics

Agent calls:
1. get_column_stats(file_path="customers.xlsx", sheet_name="Data", column="Age")
2. group_by(file_path="customers.xlsx", sheet_name="Data", columns=["Region"], agg_column="Revenue", agg_func="sum")
3. filter_rows(file_path="customers.xlsx", sheet_name="Data", filters=[{"column": "Status", "operator": "==", "value": "Active"}])

# Install development dependencies
poetry install --with dev

# Run tests
poetry run pytest

# Run linting
poetry run ruff check src/

# Run type checking
poetry run mypy src/

mcp-excel-server/
├── src/mcp_excel/           # Source code
│   ├── server.py           # MCP server entry point
│   ├── config.py           # Configuration
│   ├── backends/           # Excel backends
│   ├── tools/              # MCP tools
│   ├── resources/          # MCP resources
│   ├── prompts/            # MCP prompts
│   └── utils/              # Utilities
├── tests/                  # Test suite
├── skills/                 # Agent skills
├── examples/               # Usage examples
└── docs/                   # Documentation