volute-xls 1.1.0

MCP server for Excel analysis and multimodal AI integration - comprehensive metadata extraction and sheet image capture for agents

Volute-XLS: Excel Integration for AI Applications

A comprehensive Model Context Protocol (MCP) server that enables AI agents to interact with Microsoft Excel spreadsheets through advanced metadata extraction, content analysis, and multimodal sheet image capture.

🚀 Features

📊 Excel Analysis & Metadata Extraction

• Comprehensive workbook analysis - File properties, sheet structure, named ranges
• Detailed sheet content analysis - Cell data, formulas, data types, merged cells
• Chart and image detection - Identify visual elements in spreadsheets
• Sample data extraction - Get representative cell data for content understanding
• Cross-platform support - Works on Windows, macOS, and Linux

🖼️ Multimodal Sheet Image Capture (Windows + xlwings)

• Full sheet capture - Export entire worksheets as PNG images
• Range-specific capture - Target specific cell ranges for focused analysis
• Zoom control - Adjust capture zoom levels (10% to 400%)
• Base64 encoding - Ready for multimodal LLM analysis
• Thread-safe operations - Reliable concurrent Excel automation

🔧 Dual Architecture

• Local Server - Full COM automation with xlwings for Windows Excel integration
• Cloud Server - Cross-platform openpyxl-based analysis without local requirements
• FastMCP Integration - Built on the Model Context Protocol standard
• SDK Client Library - Easy programmatic access to all tools

📦 Installation

Basic Installation (Cross-platform)

pip install volute-xls

Full Windows Installation (with image capture)

pip install volute-xls[windows]
# or for all features
pip install volute-xls[full]

Development Installation

pip install volute-xls[dev]

🏃‍♂️ Quick Start

1. Start the Local Server

# HTTP server (default)
volute-xls-local

# STDIO for MCP clients  
volute-xls-local --transport stdio

2. Use with MCP Configuration

Add to your MCP client configuration:

Option A: Using installed package command

{
  "volute-xls-local": {
    "command": "volute-xls-local",
    "args": ["--transport", "stdio"],
    "env": {},
    "working_directory": null
  }
}

Option B: Using Python module (alternative)

{
  "volute-xls-local": {
    "command": "python",
    "args": [
      "-m",
      "volute_xls.server_local",
      "--transport",
      "stdio"
    ],
    "env": {},
    "working_directory": null
  }
}

3. Programmatic Usage

from volute_xls import create_client

# Extract Excel metadata
async with create_client("local") as client:
    metadata = await client.extract_excel_metadata(
        "path/to/workbook.xlsx",
        include_sheet_content=True,
        include_sheet_data=True
    )
    print(f"Found {len(metadata['data']['sheets'])} sheets")

# Capture sheet images (Windows + xlwings)
async with create_client("local") as client:
    images = await client.capture_excel_sheets(
        "path/to/workbook.xlsx",
        sheet_names=["Sheet1", "Dashboard"],
        image_width=1200,
        image_height=800
    )
    # Images returned as base64-encoded PNG data

🛠️ Available Tools

extract_excel_metadata

Extract comprehensive metadata from Excel workbooks including file properties, sheet structure, cell content summary, and named ranges.

Parameters:

• excel_path (str): Path to Excel file (.xlsx, .xlsm, .xls)
• include_sheet_content (bool): Include detailed sheet analysis
• include_sheet_data (bool): Include sample cell data
• output_format (str): "json" or "summary"

analyze_excel_sheets

Perform focused analysis of specific worksheets with detailed content extraction and optional sample data.

Parameters:

• excel_path (str): Path to Excel file
• sheet_names (list): Specific sheets to analyze (None for all)
• include_data_sample (bool): Include sample data
• max_rows (int): Maximum rows in sample
• include_formatting (bool): Include cell formatting

capture_excel_sheets (Windows + xlwings)

Capture Excel worksheets as PNG images for multimodal analysis.

Parameters:

• excel_path (str): Path to Excel file
• sheet_names (list): Sheet names to capture
• image_width (int): Image width (200-4000px)
• image_height (int): Image height (200-4000px)
• zoom_level (float): Zoom percentage (10-400%)

capture_excel_ranges (Windows + xlwings)

Capture specific cell ranges as images for detailed analysis.

Parameters:

• excel_path (str): Path to Excel file
• sheet_ranges (dict): {"SheetName": ["A1:C10", "E1:G5"]}
• image_width (int): Image width (100-2000px)
• image_height (int): Image height (100-2000px)

🌐 Architecture

Local Server (volute-xls-local)

• Full Excel Integration - COM automation via xlwings
• Image Capture - Native Excel sheet-to-image export
• Local File Access - Direct file system operations
• Thread Safety - Concurrent Excel operations
• Windows Optimized - Best performance on Windows with Excel installed

Cloud Server (volute-xls-server)

• Cross-Platform - Pure Python openpyxl-based analysis
• No Excel Required - Works without Microsoft Excel
• Scalable - Cloud deployment ready
• Limited Features - Metadata and analysis only (no image capture)

📋 Requirements

Basic Requirements (All Platforms)

• Python 3.8+
• fastmcp >= 2.0.0
• openpyxl >= 3.0.0
• Pillow >= 9.0.0

Windows Image Capture Requirements

• Microsoft Excel installed
• xlwings >= 0.30.0
• pywin32 >= 306

Supported File Formats

• .xlsx - Excel 2007+ workbooks
• .xlsm - Excel macro-enabled workbooks
• .xls - Legacy Excel workbooks (limited support)

🔧 Configuration

Environment Variables

# Local server configuration
LOCAL_SERVER_NAME="Volute-XLS-Local"
LOCAL_SERVER_HOST="127.0.0.1"
LOCAL_SERVER_PORT="8002"

# Cloud server configuration  
CLOUD_SERVER_NAME="Volute-XLS-Cloud"
CLOUD_SERVER_HOST="0.0.0.0"
CLOUD_SERVER_PORT="8000"

Server Options

# Start local server with custom settings
volute-xls-local --host 0.0.0.0 --port 8080

# Start cloud server
volute-xls-server --port 8000

🧪 Testing

# Install development dependencies
pip install volute-xls[dev]

# Run tests
pytest tests/

# Test with sample Excel file
python -c "
import asyncio
from volute_xls import create_client

async def test():
    async with create_client('local') as client:
        caps = await client.get_excel_capabilities()
        print('Excel capabilities:', caps)

asyncio.run(test())
"

🤝 Integration Examples

Claude Desktop MCP Configuration

{
  "mcpServers": {
    "volute-xls-local": {
      "command": "volute-xls-local",
      "args": ["--transport", "stdio"]
    }
  }
}

Programmatic Analysis Pipeline

import asyncio
from volute_xls import VoluteXLSLocalClient

async def analyze_workbook(file_path):
    async with VoluteXLSLocalClient() as client:
        # 1. Extract metadata
        metadata = await client.extract_excel_metadata(file_path)
        
        # 2. Analyze key sheets
        key_sheets = ["Summary", "Data", "Charts"]
        analysis = await client.analyze_excel_sheets(
            file_path, 
            sheet_names=key_sheets,
            include_data_sample=True
        )
        
        # 3. Capture images for multimodal analysis  
        if analysis.get('success'):
            images = await client.capture_excel_sheets(
                file_path,
                sheet_names=key_sheets
            )
            return {
                'metadata': metadata,
                'analysis': analysis, 
                'images': images
            }

# Usage
result = asyncio.run(analyze_workbook("financial_report.xlsx"))

📚 Documentation

• API Reference - docs/api.md
• Developer Guide - DEVELOPER_GUIDE.md
• Examples - examples/
• Troubleshooting - docs/troubleshooting.md

🛡️ Security & Privacy

• Local Processing - All Excel analysis happens locally
• No Data Upload - Files never leave your machine with local server
• Thread Safety - Concurrent operations are protected
• Resource Management - Automatic cleanup of temporary files and Excel instances

🗺️ Roadmap

• Enhanced Chart Analysis - Detailed chart metadata extraction
• Pivot Table Support - Analysis of pivot tables and data models
• VBA Code Detection - Identify and analyze VBA macros
• Performance Optimization - Faster processing of large workbooks
• Additional Image Formats - Support for JPEG, SVG export
• Cloud Image Capture - Server-side image generation without xlwings

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

git clone https://gitlab.com/coritan/volute-xls.git
cd volute-xls
pip install -e .[dev,full]
pre-commit install

📄 License

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

🙏 Acknowledgments

• FastMCP - For the excellent Model Context Protocol framework
• openpyxl - For cross-platform Excel file processing
• xlwings - For Windows Excel COM automation
• Pillow - For image processing capabilities
• Model Context Protocol - For the agent integration standard

---

Created with ❤️ for the AI agent community

For questions, issues, or feature requests, please visit our GitLab repository or open an issue.