MCP Excel Office Server

Powerful MCP server for programmatic Excel (.xlsx) manipulation and automation

📖 Description

A comprehensive MCP (Model Context Protocol) server that provides AI assistants with powerful Excel manipulation capabilities. This server enables programmatic creation, modification, and management of Excel files through standardized MCP tools, supporting data operations, formatting, formulas, charts, and PostgreSQL database integration.

📋 Table of Contents

• ✨ Key Features
• 🚀 Installation
• ⚙️ Deployment Modes
  • DXT Package Deployment
  • Traditional MCP Server
  • Standalone CLI
• 🔧 Configuration
• 📚 Available Tools
• 🧪 Testing
• 🧩 Project Structure
• 🔧 Development
• 🤝 Contributing
• 📄 License

✨ Key Features

• 📊 Comprehensive Excel Operations: Create, read, modify workbooks and worksheets with full data manipulation support
• 🎨 Advanced Formatting: Apply styles, fonts, colors, borders, and cell formatting with precision
• 📈 Data Visualization: Generate charts, pivot tables, and graphics programmatically
• 🗄️ Database Integration: Direct PostgreSQL integration for seamless data import/export
• ⚡ Formula Support: Apply and validate Excel formulas with error handling
• 🔒 Security First: File path validation, access control, and robust error handling
• 🚀 Multiple Deployment Modes: DXT package, traditional MCP server, or standalone CLI
• 🤖 AI-Ready: Optimized for AI assistant integration via Model Context Protocol

🚀 Installation

📋 Prerequisites

• Python 3.11+: Modern Python with type hints support
• UV Package Manager: Install UV (recommended) or use pip
• Git: For cloning the repository
• Desktop Extensions (DXT) : for create packages .dxt for claude desktop Install DXT

🔄 Clone the Repository

git clone https://github.com/LuiccianDev/mcp_excel_office.git
cd mcp_excel_office

⚡ Installation with UV (Recommended)

# Install production dependencies
uv sync

# Install with development dependencies
uv sync --dev

# Install all dependency groups (dev + test)
uv sync --all-groups

🐍 Alternative: Installation with pip

# Install the package
pip install .

# Development installation (editable)
pip install -e ".[dev,test]"

🏗️ Build and Package

# Build distributable package
uv build

# Install from built package
uv pip install dist/mcp_excel-*.whl

⚙️ Deployment Modes

The MCP Excel Office Server supports three deployment modes to fit different workflows and environments:

DXT Package Deployment

Best for: Integrated DXT ecosystem users who want seamless configuration management.

1. Package the project:

   dxt pack

2. Configuration: The DXT package automatically handles dependencies and provides user-friendly configuration through the manifest.json:

   • directory: Base directory for file operations
   • postgres_connection_string: PostgreSQL database connection (marked as sensitive)

3. Usage: Once packaged, the tool integrates directly with DXT-compatible clients with automatic user configuration variable substitution.

4. Server Configuration: this proyect include the files manifest.json for building package .dxt

for more details see DXT Package Documentation.

Traditional MCP Server

Best for: Standard MCP server deployments with existing MCP infrastructure.

Add to your MCP configuration file (e.g., Claude Desktop's mcp_config.json):

# create packages
uv build
#install packages
pip install dist/archivo*.whl

The next steps is configuractiosn en mcp

{
  "mcpServers": {
    "mcp_excel": {
      "command": "uv",
      "args": ["run", "mcp_excel"],
      "env": {
        "DIRECTORY": "user/to/path/directory",
        "POSTGRES_CONNECTION_STRING": "postgres_connection_string"
      }
    }
  }
}

Alternative configuration with CLI arguments:

{
  "mcpServers": {
    "mcp_excel": {
      "command": "uv",
      "args": [
        "run", "-m", "mcp_excel",
        "--path", "user/to/path/directory",
        "--postgres", "postgres_connection_string"
      ]
    }
  }
}

Standalone CLI

Best for: Direct command-line usage, scripting, and automation without MCP protocol overhead.

# Run with environment variables
export DIRECTORY="/path/to/your/files"
export POSTGRES_CONNECTION_STRING="postgresql://user:pass@localhost/db"
python -m mcp_excel

# Or run with command-line arguments
python -m mcp_excel --path "/path/to/files" --postgres "postgresql://user:pass@localhost/db"

# Using UV
uv run mcp_excel_office --help

🐳 Instalación con Docker

Puedes instalar y ejecutar el servidor MCP Excel Office fácilmente usando Docker. Esto garantiza un entorno aislado y reproducible.

Para más detalles y opciones avanzadas de configuración con Docker, consulta el archivo Docker.md.

🔧 Configuration

Environment Variables

• DIRECTORY: Base directory for file operations (required for security)
• POSTGRES_CONNECTION_STRING: PostgreSQL connection string for database operations (optional)

Configuration Validation

The server validates all configuration on startup and provides clear error messages for:

• Missing required environment variables
• Invalid directory paths
• Malformed database connection strings
• File access permissions

📚 Available Tools

Todas las herramientas disponibles para manipulación de Excel, operaciones de datos, formato, fórmulas, gráficos y base de datos están documentadas en detalle en el archivo TOOLS.md. Consulta ese archivo para ver la lista completa de herramientas, sus parámetros y ejemplos de uso.

🧩 Project Structure

mcp_excel_office/
├── src/mcp_excel/              # Main package
│   ├── __init__.py            # Package initialization
│   ├── __main__.py            # CLI entry point
│   ├── server.py              # MCP server implementation
│   ├── register_tools.py      # Tool registration
│   ├── tools/                 # MCP tool implementations
│   │   ├── content_tools.py   # Data read/write operations
│   │   ├── excel_tools.py     # Basic workbook operations
│   │   ├── format_tools.py    # Cell formatting and styling
│   │   ├── formulas_excel_tools.py  # Formula operations
│   │   ├── graphics_tools.py  # Charts and visualizations
│   │   └── db_tools.py        # Database integration
│   ├── core/                  # Core functionality
│   ├── utils/                 # Utility functions
│   └── exceptions/            # Custom exceptions
├── tests/                     # Test suite
│   ├── test_content_tools.py  # Content operations tests
│   ├── test_excel_tools.py    # Basic operations tests
│   ├── test_format_tools.py   # Formatting tests
│   ├── test_formulas_excel_tools.py  # Formula tests
│   ├── test_graphics_tools.py # Graphics tests
│   └── test_db_tools.py       # Database tests
├── pyproject.toml             # Project configuration
├── manifest.json              # DXT package configuration
├── TOOLS.md                   # Detailed tool documentation
└── README.md                  # This file

🧪 Testing

Run Tests

# Run all tests
uv run pytest

🔧 Development

Development Setup

# Install development dependencies
uv sync --dev

# Install pre-commit hooks
uv run pre-commit install

# Run quality checks
uv run pre-commit run --all-files

Code Quality Standards

# Format code with Ruff
uv run ruff format

# Check code style
uv run ruff check

# Type checking with MyPy
uv run mypy src/

# Run all quality checks
uv run pre-commit run --all-files

Development Commands

• uv sync --dev: Install development dependencies
• uv run ruff check: Code style and quality checks
• uv run mypy src/: Type checking with strict configuration
• uv run pytest: Run test suite with coverage
• uv build: Build distributable package

🤝 Contributing

We welcome contributions! Please follow these guidelines:

🐛 Issues and Support

• Bug Reports: Open an issue with detailed reproduction steps
• Feature Requests: Describe your use case and proposed solution
• Questions: Check existing issues or start a discussion

📄 License

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

---

MCP Excel Office Server

Empowering AI assistants with comprehensive Excel manipulation capabilities

🏠 GitHub • 🔗 MCP Protocol • 📚 Tool Documentation

Created with by LuiccianDev