<<<<<<< HEAD

Excel MCP Server with Supabase Storage

Python Version License: MIT MCP Compatible

A powerful MCP (Model Context Protocol) server for Excel operations with seamless Supabase Storage integration. Handle Excel files programmatically without requiring Microsoft Office or WPS installation.

🌟 Features

• ✅ Excel Parsing: Convert Excel files to JSON with complete formatting information
• ✅ Excel Generation: Create formatted Excel files from JSON data
• ✅ Advanced Formatting: Modify cell styles, merge cells, adjust dimensions
• ✅ Formula Support: Execute and calculate 20+ common Excel formulas
• ✅ Multi-Sheet Operations: Merge multiple Excel files into a single workbook
• ✅ Supabase Integration: Direct read/write operations with Supabase Storage
• ✅ Zero Dependencies: No Microsoft Office or WPS required
• ✅ Cross-Platform: Works on Windows, Linux, and macOS

🚀 Quick Start

Installation

Option 1: Install from GitHub (Recommended for now)

# Install and run directly
uvx --from git+https://github.com/1126misakp/Excel-MCP-Server-with-Supabase-Storage mcp-excel-supabase

Option 2: Install from PyPI (Coming soon)

# Once published to PyPI, you can use:
uvx mcp-excel-supabase

Option 3: Install from local source

# Clone the repository
git clone https://github.com/1126misakp/Excel-MCP-Server-with-Supabase-Storage
cd Excel-MCP-Server-with-Supabase-Storage

# Install in development mode
pip install -e .

# Run the server
mcp-excel-supabase

Configuration

1. Create a .env file in your project directory:

cp .env.example .env

2. Edit .env and add your Supabase credentials:

SUPABASE_URL=https://yourproject.supabase.co
SUPABASE_KEY=your-service-role-key-here

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

If installing from GitHub:

{
  "mcpServers": {
    "excel-supabase": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/1126misakp/Excel-MCP-Server-with-Supabase-Storage",
        "mcp-excel-supabase"
      ],
      "env": {
        "SUPABASE_URL": "https://yourproject.supabase.co",
        "SUPABASE_KEY": "your-service-role-key-here"
      }
    }
  }
}

If installing from PyPI (once published):

{
  "mcpServers": {
    "excel-supabase": {
      "command": "uvx",
      "args": ["mcp-excel-supabase"],
      "env": {
        "SUPABASE_URL": "https://yourproject.supabase.co",
        "SUPABASE_KEY": "your-service-role-key-here"
      }
    }
  }
}

Transport Modes

The server supports three transport modes via environment variables:

STDIO Mode (Default)

Best for Claude Desktop and command-line tools:

{
  "mcpServers": {
    "excel-supabase": {
      "command": "uvx",
      "args": ["mcp-excel-supabase"],
      "env": {
        "SUPABASE_URL": "https://yourproject.supabase.co",
        "SUPABASE_KEY": "your-service-role-key-here"
      }
    }
  }
}

HTTP Mode

Best for Cherry Studio and web clients:

{
  "mcpServers": {
    "excel-supabase": {
      "command": "uvx",
      "args": ["mcp-excel-supabase"],
      "env": {
        "SUPABASE_URL": "https://yourproject.supabase.co",
        "SUPABASE_KEY": "your-service-role-key-here",
        "MCP_TRANSPORT": "http",
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "8000"
      }
    }
  }
}

SSE Mode

For legacy SSE clients:

{
  "mcpServers": {
    "excel-supabase": {
      "command": "uvx",
      "args": ["mcp-excel-supabase"],
      "env": {
        "SUPABASE_URL": "https://yourproject.supabase.co",
        "SUPABASE_KEY": "your-service-role-key-here",
        "MCP_TRANSPORT": "sse",
        "MCP_HOST": "127.0.0.1",
        "MCP_PORT": "8000"
      }
    }
  }
}

Environment Variables:

• MCP_TRANSPORT: Transport mode (stdio | http | sse), default: stdio
• MCP_HOST: Server host address, default: 127.0.0.1
• MCP_PORT: Server port, default: 8000

For detailed transport configuration, see docs/TRANSPORT_MODES.md.

🛠️ Available Tools

This server provides 12 MCP tools for comprehensive Excel operations:

Tool	Description
parse_excel_to_json	Parse Excel files to JSON format
create_excel_from_json	Generate Excel files from JSON data
modify_cell_format	Edit cell formatting (fonts, colors, borders)
merge_cells	Merge cell ranges
unmerge_cells	Unmerge cell ranges
set_row_heights	Adjust row heights
set_column_widths	Adjust column widths
manage_storage	Upload/download files to/from Supabase
set_formula	Set Excel formulas in cells
recalculate_formulas	Recalculate all formulas in a workbook
manage_sheets	Create, delete, rename, copy, move sheets
merge_excel_files	Merge multiple Excel files

See API Reference for detailed documentation.

📖 Usage Examples

Parse Excel to JSON

# Parse a local file
result = parse_excel_to_json(
    file_path="data/sales_q1.xlsx",
    extract_formats=True
)

# Access parsed data
workbook = result["workbook"]
sheets = workbook["sheets"]

Create Excel from JSON

# Create a simple Excel file
workbook_data = {
    "sheets": [{
        "name": "Sales",
        "rows": [
            {"cells": [
                {"value": "Product", "row": 1, "column": 1},
                {"value": "Revenue", "row": 1, "column": 2}
            ]},
            {"cells": [
                {"value": "Product A", "row": 2, "column": 1},
                {"value": 1000, "row": 2, "column": 2}
            ]}
        ]
    }]
}

create_excel_from_json(
    workbook_data=workbook_data,
    output_path="output/sales.xlsx",
    apply_formats=True
)

Format Cells

# Format header row
modify_cell_format(
    file_path="data/sales.xlsx",
    sheet_name="Sheet1",
    cell_range="A1:J1",
    format_spec={
        "font": {"name": "Arial", "size": 12, "bold": True, "color": "FFFFFF"},
        "fill": {"color": "4472C4"},
        "alignment": {"horizontal": "center", "vertical": "center"}
    }
)

Set Formulas

# Set a SUM formula
set_formula(
    file_path="data/sales.xlsx",
    sheet_name="Sheet1",
    cell="D10",
    formula="=SUM(D2:D9)"
)

# Recalculate all formulas
recalculate_formulas(
    file_path="data/sales.xlsx"
)

Merge Excel Files

# Merge quarterly reports
merge_excel_files(
    file_paths=["q1.xlsx", "q2.xlsx", "q3.xlsx", "q4.xlsx"],
    output_path="annual_report.xlsx",
    handle_duplicates="rename"  # or "skip" or "overwrite"
)

Supabase Storage Operations

# Upload file to Supabase
manage_storage(
    operation="upload",
    local_path="output/report.xlsx",
    remote_path="reports/2024/annual.xlsx"
)

# Download file from Supabase
manage_storage(
    operation="download",
    remote_path="reports/2024/annual.xlsx",
    local_path="downloads/annual.xlsx"
)

# List files
manage_storage(
    operation="list",
    remote_path="reports/2024/"
)

For more examples, see the Examples Directory.

📚 Documentation

• Product Requirements Document (PRD)
• API Reference - Complete API documentation for all 12 tools
• Usage Examples - 6 end-to-end examples
  • Basic Parsing
  • Excel Generation
  • Cell Formatting
  • Formula Operations
  • File Merging
  • Supabase Integration
• Architecture - System architecture and design patterns
• Development Guide - Contributing and development workflow
• Troubleshooting - Common issues and solutions

🛠️ Development

Local Setup

# Clone the repository
git clone https://github.com/1126misakp/Excel-MCP-Server-with-Supabase-Storage
cd Excel-MCP-Server-with-Supabase-Storage

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Format code
black .

Project Structure

Excel-MCP-Server-with-Supabase-Storage/
├── src/mcp_excel_supabase/      # Source code
│   ├── excel/                    # Excel operations
│   ├── storage/                  # Supabase integration
│   └── utils/                    # Utilities
├── tests/                        # Test suite
├── docs/                         # Documentation
└── PRD.md                        # Product Requirements

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov

# Run specific test file
pytest tests/test_parser.py

📋 Requirements

• Python 3.9+
• Supabase account with Storage API access
• No Microsoft Office or WPS installation required

🤝 Contributing

Contributions are welcome! Please see Development Guide for guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

Version 1.0 (Current)

• ✅ Core Excel parsing and generation
• ✅ Supabase Storage integration
• ✅ Basic formatting support
• ✅ 20+ common formulas

Version 1.1 (Planned)

• 📋 Chart generation support
• 📋 Conditional formatting
• 📋 Data validation rules
• 📋 Advanced formula functions
• 📋 WebUI control panel

🌐 Related Projects

• openpyxl - Excel file operations
• Supabase - Cloud storage backend
• MCP Protocol - Model Context Protocol

📊 Performance

Benchmarked on a standard development machine (Intel i5, 8GB RAM):

Operation	Target	Actual	Status
Parse 1MB file	<2s	0.598s	✅ 3.3x faster
Generate 1000 rows	<3s	0.026s	✅ 115x faster
Merge 10 files	<8s	0.117s	✅ 68x faster
Batch 20 files	<10s	0.192s	✅ 52x faster
Format 1000 cells	<0.5s	0.089s	✅ 5.6x faster

Performance Optimizations:

• ✅ LRU caching for parsed files (128 entries)
• ✅ Thread pool concurrency (8 workers)
• ✅ Streaming I/O for large files
• ✅ Memory-efficient processing (5000 rows = +0.04MB)

---

Made with ❤️ by 1126misakp

This project is actively maintained and welcomes contributions from the community.

Excel MCP Server with Supabase Storage

Python Version License: MIT MCP Compatible

A powerful MCP (Model Context Protocol) server for Excel operations with seamless Supabase Storage integration. Handle Excel files programmatically without requiring Microsoft Office or WPS installation.

🌟 Features

• ✅ Excel Parsing: Convert Excel files to JSON with complete formatting information
• ✅ Excel Generation: Create formatted Excel files from JSON data
• ✅ Advanced Formatting: Modify cell styles, merge cells, adjust dimensions
• ✅ Formula Support: Execute and calculate 20+ common Excel formulas
• ✅ Multi-Sheet Operations: Merge multiple Excel files into a single workbook
• ✅ Supabase Integration: Direct read/write operations with Supabase Storage
• ✅ Zero Dependencies: No Microsoft Office or WPS required
• ✅ Cross-Platform: Works on Windows, Linux, and macOS

🚀 Quick Start

Installation

Option 1: Install from GitHub (Recommended for now)

# Install and run directly
uvx --from git+https://github.com/1126misakp/Excel-MCP-Server-with-Supabase-Storage mcp-excel-supabase

Option 2: Install from PyPI (Coming soon)

# Once published to PyPI, you can use:
uvx mcp-excel-supabase

Option 3: Install from local source

# Clone the repository
git clone https://github.com/1126misakp/Excel-MCP-Server-with-Supabase-Storage
cd Excel-MCP-Server-with-Supabase-Storage

# Install in development mode
pip install -e .

# Run the server
mcp-excel-supabase

Configuration

1. Create a .env file in your project directory:

cp .env.example .env

2. Edit .env and add your Supabase credentials:

SUPABASE_URL=https://yourproject.supabase.co
SUPABASE_KEY=your-service-role-key-here

Claude Desktop Configuration

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

If installing from GitHub:

{
  "mcpServers": {
    "excel-supabase": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/1126misakp/Excel-MCP-Server-with-Supabase-Storage",
        "mcp-excel-supabase"
      ],
      "env": {
        "SUPABASE_URL": "https://yourproject.supabase.co",
        "SUPABASE_KEY": "your-service-role-key-here"
      }
    }
  }
}

If installing from PyPI (once published):

{
  "mcpServers": {
    "excel-supabase": {
      "command": "uvx",
      "args": ["mcp-excel-supabase"],
      "env": {
        "SUPABASE_URL": "https://yourproject.supabase.co",
        "SUPABASE_KEY": "your-service-role-key-here"
      }
    }
  }
}

🛠️ Available Tools

This server provides 12 MCP tools for comprehensive Excel operations:

Tool	Description
parse_excel_to_json	Parse Excel files to JSON format
create_excel_from_json	Generate Excel files from JSON data
modify_cell_format	Edit cell formatting (fonts, colors, borders)
merge_cells	Merge cell ranges
unmerge_cells	Unmerge cell ranges
set_row_heights	Adjust row heights
set_column_widths	Adjust column widths
manage_storage	Upload/download files to/from Supabase
set_formula	Set Excel formulas in cells
recalculate_formulas	Recalculate all formulas in a workbook
manage_sheets	Create, delete, rename, copy, move sheets
merge_excel_files	Merge multiple Excel files

See API Reference for detailed documentation.

📖 Usage Examples

Parse Excel to JSON

# Parse a local file
result = parse_excel_to_json(
    file_path="data/sales_q1.xlsx",
    extract_formats=True
)

# Access parsed data
workbook = result["workbook"]
sheets = workbook["sheets"]

Create Excel from JSON

# Create a simple Excel file
workbook_data = {
    "sheets": [{
        "name": "Sales",
        "rows": [
            {"cells": [
                {"value": "Product", "row": 1, "column": 1},
                {"value": "Revenue", "row": 1, "column": 2}
            ]},
            {"cells": [
                {"value": "Product A", "row": 2, "column": 1},
                {"value": 1000, "row": 2, "column": 2}
            ]}
        ]
    }]
}

create_excel_from_json(
    workbook_data=workbook_data,
    output_path="output/sales.xlsx",
    apply_formats=True
)

Format Cells

# Format header row
modify_cell_format(
    file_path="data/sales.xlsx",
    sheet_name="Sheet1",
    cell_range="A1:J1",
    format_spec={
        "font": {"name": "Arial", "size": 12, "bold": True, "color": "FFFFFF"},
        "fill": {"color": "4472C4"},
        "alignment": {"horizontal": "center", "vertical": "center"}
    }
)

Set Formulas

# Set a SUM formula
set_formula(
    file_path="data/sales.xlsx",
    sheet_name="Sheet1",
    cell="D10",
    formula="=SUM(D2:D9)"
)

# Recalculate all formulas
recalculate_formulas(
    file_path="data/sales.xlsx"
)

Merge Excel Files

# Merge quarterly reports
merge_excel_files(
    file_paths=["q1.xlsx", "q2.xlsx", "q3.xlsx", "q4.xlsx"],
    output_path="annual_report.xlsx",
    handle_duplicates="rename"  # or "skip" or "overwrite"
)

Supabase Storage Operations

# Upload file to Supabase
manage_storage(
    operation="upload",
    local_path="output/report.xlsx",
    remote_path="reports/2024/annual.xlsx"
)

# Download file from Supabase
manage_storage(
    operation="download",
    remote_path="reports/2024/annual.xlsx",
    local_path="downloads/annual.xlsx"
)

# List files
manage_storage(
    operation="list",
    remote_path="reports/2024/"
)

For more examples, see the Examples Directory.

📚 Documentation

• Product Requirements Document (PRD)
• API Reference - Complete API documentation for all 12 tools
• Usage Examples - 6 end-to-end examples
  • Basic Parsing
  • Excel Generation
  • Cell Formatting
  • Formula Operations
  • File Merging
  • Supabase Integration
• Architecture - System architecture and design patterns
• Development Guide - Contributing and development workflow
• Troubleshooting - Common issues and solutions

🛠️ Development

Local Setup

# Clone the repository
git clone https://github.com/1126misakp/Excel-MCP-Server-with-Supabase-Storage
cd Excel-MCP-Server-with-Supabase-Storage

# Install dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linter
ruff check .

# Format code
black .

Project Structure

Excel-MCP-Server-with-Supabase-Storage/
├── src/mcp_excel_supabase/      # Source code
│   ├── excel/                    # Excel operations
│   ├── storage/                  # Supabase integration
│   └── utils/                    # Utilities
├── tests/                        # Test suite
├── docs/                         # Documentation
└── PRD.md                        # Product Requirements

🧪 Testing

# Run all tests
pytest

# Run with coverage
pytest --cov

# Run specific test file
pytest tests/test_parser.py

📋 Requirements

• Python 3.9+
• Supabase account with Storage API access
• No Microsoft Office or WPS installation required

🤝 Contributing

Contributions are welcome! Please see Development Guide for guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

Version 1.0 (Current)

• ✅ Core Excel parsing and generation
• ✅ Supabase Storage integration
• ✅ Basic formatting support
• ✅ 20+ common formulas

Version 1.1 (Planned)

• 📋 Chart generation support
• 📋 Conditional formatting
• 📋 Data validation rules
• 📋 Advanced formula functions
• 📋 WebUI control panel

🌐 Related Projects

• openpyxl - Excel file operations
• Supabase - Cloud storage backend
• MCP Protocol - Model Context Protocol

📊 Performance

Benchmarked on a standard development machine (Intel i5, 8GB RAM):

Operation	Target	Actual	Status
Parse 1MB file	<2s	0.598s	✅ 3.3x faster
Generate 1000 rows	<3s	0.026s	✅ 115x faster
Merge 10 files	<8s	0.117s	✅ 68x faster
Batch 20 files	<10s	0.192s	✅ 52x faster
Format 1000 cells	<0.5s	0.089s	✅ 5.6x faster

Performance Optimizations:

• ✅ LRU caching for parsed files (128 entries)
• ✅ Thread pool concurrency (8 workers)
• ✅ Streaming I/O for large files
• ✅ Memory-efficient processing (5000 rows = +0.04MB)

---

Made with ❤️ by 1126misakp

This project is actively maintained and welcomes contributions from the community.

6dc69b6 (Release v1.0.0: Complete Excel MCP Server with Supabase Storage)