excel-mcp-server 0.1.0__tar.gz

excel_mcp_server-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Build and Distribution
+__pycache__/
+*.py[cod]
+build/
+dist/
+src/*.egg-info/
+
+# Development Environment
+.venv/
+.env
+
+# IDE
+.vscode/
+.idea/
+.cursor/
+.cursorignore
+.cursorrules
+.specstory
+
+# Testing and Linting
+.coverage
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+htmlcov/
+tests/
+
+# Project Files
+extras/
+.notes/
+logs/
+output/
+*.xlsx
+*.xls
+*.log 
+excel_files/

excel_mcp_server-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Haris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

excel_mcp_server-0.1.0/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: excel-mcp-server
+Version: 0.1.0
+Summary: MCP server for Excel file manipulation
+Author-email: haris <haris.musa@outlook.com>
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: openpyxl>=3.1.2
+Description-Content-Type: text/markdown
+
+# Excel MCP Server
+[![smithery badge](https://smithery.ai/badge/@haris-musa/excel-mcp-server)](https://smithery.ai/server/@haris-musa/excel-mcp-server)
+
+A Model Context Protocol (MCP) server implementation that provides Excel file manipulation capabilities without requiring Microsoft Excel installation. This server enables workbook creation, data manipulation, formatting, and advanced Excel features.
+
+## Requirements
+
+- Python 3.10+
+- MCP SDK 1.2.0+
+- OpenPyXL 3.1.2+
+
+## Components
+
+### Resources
+
+The server provides Excel workbook manipulation through OpenPyXL:
+
+- Creates and modifies Excel workbooks
+- Manages worksheets and ranges
+- Handles formatting and styles
+- Supports charts and pivot tables
+
+### Tools
+
+This server provides a comprehensive set of Excel manipulation tools. For detailed documentation of all available tools, their parameters, and usage examples, please refer to [TOOLS.md](TOOLS.md).
+
+The tools include capabilities for:
+
+- Workbook and worksheet management
+- Data reading and writing
+- Formatting and styling
+- Charts and visualizations
+- Pivot tables and data analysis
+
+See [TOOLS.md](TOOLS.md) for complete documentation.
+
+## Features
+
+- Full Excel Support: Comprehensive Excel functionality
+- Data Manipulation: Read, write, and transform data
+- Advanced Features: Charts, pivot tables, and formatting
+- Error Handling: Comprehensive error handling with clear messages
+
+## Usage
+
+### Environment Configuration
+
+The server can be configured using the following environment variables:
+
+- `EXCEL_FILES_PATH`: Directory where Excel files will be stored (default: `./excel_files`)
+
+You can set this in different ways:
+
+Windows CMD:
+
+```cmd
+set EXCEL_FILES_PATH=C:\path\to\excel\files
+uv run excel-mcp-server
+```
+
+Windows PowerShell:
+
+```powershell
+$env:EXCEL_FILES_PATH="C:\path\to\excel\files"
+uv run excel-mcp-server
+```
+
+Linux/MacOS:
+
+```bash
+export EXCEL_FILES_PATH=/path/to/excel/files
+uv run excel-mcp-server
+```
+
+Or in Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "excel": {
+      "command": "uv run excel-mcp-server",
+      "transport": "sse",
+      "env": {
+        "EXCEL_FILES_PATH": "/path/to/excel/files"
+      }
+    }
+  }
+}
+```
+
+### Starting the Server
+
+Start the server:
+
+```bash
+uv run excel-mcp-server
+```
+
+The server will start in SSE mode and wait for connections from MCP clients.
+
+### Connecting in Cursor IDE
+
+After starting the server, connect to the SSE endpoint in Cursor IDE:
+
+```
+http://localhost:8000/sse
+```
+
+The Excel MCP tools will be available through the agent.
+
+For available tools and their usage, please refer to [TOOLS.md](TOOLS.md).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

excel_mcp_server-0.1.0/README.md

@@ -0,0 +1,115 @@
+# Excel MCP Server
+[![smithery badge](https://smithery.ai/badge/@haris-musa/excel-mcp-server)](https://smithery.ai/server/@haris-musa/excel-mcp-server)
+
+A Model Context Protocol (MCP) server implementation that provides Excel file manipulation capabilities without requiring Microsoft Excel installation. This server enables workbook creation, data manipulation, formatting, and advanced Excel features.
+
+## Requirements
+
+- Python 3.10+
+- MCP SDK 1.2.0+
+- OpenPyXL 3.1.2+
+
+## Components
+
+### Resources
+
+The server provides Excel workbook manipulation through OpenPyXL:
+
+- Creates and modifies Excel workbooks
+- Manages worksheets and ranges
+- Handles formatting and styles
+- Supports charts and pivot tables
+
+### Tools
+
+This server provides a comprehensive set of Excel manipulation tools. For detailed documentation of all available tools, their parameters, and usage examples, please refer to [TOOLS.md](TOOLS.md).
+
+The tools include capabilities for:
+
+- Workbook and worksheet management
+- Data reading and writing
+- Formatting and styling
+- Charts and visualizations
+- Pivot tables and data analysis
+
+See [TOOLS.md](TOOLS.md) for complete documentation.
+
+## Features
+
+- Full Excel Support: Comprehensive Excel functionality
+- Data Manipulation: Read, write, and transform data
+- Advanced Features: Charts, pivot tables, and formatting
+- Error Handling: Comprehensive error handling with clear messages
+
+## Usage
+
+### Environment Configuration
+
+The server can be configured using the following environment variables:
+
+- `EXCEL_FILES_PATH`: Directory where Excel files will be stored (default: `./excel_files`)
+
+You can set this in different ways:
+
+Windows CMD:
+
+```cmd
+set EXCEL_FILES_PATH=C:\path\to\excel\files
+uv run excel-mcp-server
+```
+
+Windows PowerShell:
+
+```powershell
+$env:EXCEL_FILES_PATH="C:\path\to\excel\files"
+uv run excel-mcp-server
+```
+
+Linux/MacOS:
+
+```bash
+export EXCEL_FILES_PATH=/path/to/excel/files
+uv run excel-mcp-server
+```
+
+Or in Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "excel": {
+      "command": "uv run excel-mcp-server",
+      "transport": "sse",
+      "env": {
+        "EXCEL_FILES_PATH": "/path/to/excel/files"
+      }
+    }
+  }
+}
+```
+
+### Starting the Server
+
+Start the server:
+
+```bash
+uv run excel-mcp-server
+```
+
+The server will start in SSE mode and wait for connections from MCP clients.
+
+### Connecting in Cursor IDE
+
+After starting the server, connect to the SSE endpoint in Cursor IDE:
+
+```
+http://localhost:8000/sse
+```
+
+The Excel MCP tools will be available through the agent.
+
+For available tools and their usage, please refer to [TOOLS.md](TOOLS.md).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

excel_mcp_server-0.1.0/excel_mcp/__main__.py

@@ -0,0 +1,21 @@
+import asyncio
+from .server import run_server
+
+def main():
+    """Start the Excel MCP server."""
+    try:
+        print("Excel MCP Server")
+        print("---------------")
+        print("Starting server... Press Ctrl+C to exit")
+        asyncio.run(run_server())
+    except KeyboardInterrupt:
+        print("\nShutting down server...")
+    except Exception as e:
+        print(f"\nError: {e}")
+        import traceback
+        traceback.print_exc()
+    finally:
+        print("Server stopped.")
+
+if __name__ == "__main__":
+    main() 

excel_mcp_server-0.1.0/excel_mcp/calculations.py

@@ -0,0 +1,60 @@
+from typing import Any
+import logging
+
+from .workbook import get_or_create_workbook
+from .cell_utils import validate_cell_reference
+from .exceptions import ValidationError, CalculationError
+from .validation import validate_formula
+
+logger = logging.getLogger(__name__)
+
+def apply_formula(
+    filepath: str,
+    sheet_name: str,
+    cell: str,
+    formula: str
+) -> dict[str, Any]:
+    """Apply any Excel formula to a cell."""
+    try:
+        if not validate_cell_reference(cell):
+            raise ValidationError(f"Invalid cell reference: {cell}")
+            
+        wb = get_or_create_workbook(filepath)
+        if sheet_name not in wb.sheetnames:
+            raise ValidationError(f"Sheet '{sheet_name}' not found")
+            
+        sheet = wb[sheet_name]
+        
+        # Ensure formula starts with =
+        if not formula.startswith('='):
+            formula = f'={formula}'
+            
+        # Validate formula syntax
+        is_valid, message = validate_formula(formula)
+        if not is_valid:
+            raise CalculationError(f"Invalid formula syntax: {message}")
+            
+        try:
+            # Apply formula to the cell
+            cell_obj = sheet[cell]
+            cell_obj.value = formula
+        except Exception as e:
+            raise CalculationError(f"Failed to apply formula to cell: {str(e)}")
+            
+        try:
+            wb.save(filepath)
+        except Exception as e:
+            raise CalculationError(f"Failed to save workbook after applying formula: {str(e)}")
+        
+        return {
+            "message": f"Applied formula '{formula}' to cell {cell}",
+            "cell": cell,
+            "formula": formula
+        }
+        
+    except (ValidationError, CalculationError) as e:
+        logger.error(str(e))
+        raise
+    except Exception as e:
+        logger.error(f"Failed to apply formula: {e}")
+        raise CalculationError(str(e))

excel_mcp_server-0.1.0/excel_mcp/cell_utils.py

@@ -0,0 +1,54 @@
+import re
+
+from openpyxl.utils import column_index_from_string
+
+def parse_cell_range(
+    cell_ref: str,
+    end_ref: str | None = None
+) -> tuple[int, int, int | None, int | None]:
+    """Parse Excel cell reference into row and column indices."""
+    if end_ref:
+        start_cell = cell_ref
+        end_cell = end_ref
+    else:
+        start_cell = cell_ref
+        end_cell = None
+
+    match = re.match(r"([A-Z]+)([0-9]+)", start_cell.upper())
+    if not match:
+        raise ValueError(f"Invalid cell reference: {start_cell}")
+    col_str, row_str = match.groups()
+    start_row = int(row_str)
+    start_col = column_index_from_string(col_str)
+
+    if end_cell:
+        match = re.match(r"([A-Z]+)([0-9]+)", end_cell.upper())
+        if not match:
+            raise ValueError(f"Invalid cell reference: {end_cell}")
+        col_str, row_str = match.groups()
+        end_row = int(row_str)
+        end_col = column_index_from_string(col_str)
+    else:
+        end_row = None
+        end_col = None
+
+    return start_row, start_col, end_row, end_col
+
+def validate_cell_reference(cell_ref: str) -> bool:
+    """Validate Excel cell reference format (e.g., 'A1', 'BC123')"""
+    if not cell_ref:
+        return False
+
+    # Split into column and row parts
+    col = row = ""
+    for c in cell_ref:
+        if c.isalpha():
+            if row:  # Letters after numbers not allowed
+                return False
+            col += c
+        elif c.isdigit():
+            row += c
+        else:
+            return False
+
+    return bool(col and row) 

excel_mcp_server-0.1.0/excel_mcp/chart.py

@@ -0,0 +1,237 @@
+from typing import Any, Optional, Dict
+import logging
+from enum import Enum
+
+from openpyxl import load_workbook
+from openpyxl.chart import (
+    BarChart, LineChart, PieChart, ScatterChart, 
+    AreaChart, Reference, Series
+)
+from openpyxl.chart.label import DataLabelList
+from openpyxl.chart.legend import Legend
+from openpyxl.chart.axis import ChartLines
+from openpyxl.drawing.spreadsheet_drawing import (
+    AnchorMarker, OneCellAnchor, SpreadsheetDrawing
+)
+from openpyxl.utils import column_index_from_string
+
+from .cell_utils import parse_cell_range
+from .exceptions import ValidationError, ChartError
+
+logger = logging.getLogger(__name__)
+
+class ChartType(str, Enum):
+    """Supported chart types"""
+    LINE = "line"
+    BAR = "bar"
+    PIE = "pie"
+    SCATTER = "scatter"
+    AREA = "area"
+    BUBBLE = "bubble"
+    STOCK = "stock"
+    SURFACE = "surface"
+    RADAR = "radar"
+
+class ChartStyle:
+    """Chart style configuration"""
+    def __init__(
+        self,
+        title_size: int = 14,
+        title_bold: bool = True,
+        axis_label_size: int = 12,
+        show_legend: bool = True,
+        legend_position: str = "r",
+        show_data_labels: bool = True,
+        grid_lines: bool = False,
+        style_id: int = 2
+    ):
+        self.title_size = title_size
+        self.title_bold = title_bold
+        self.axis_label_size = axis_label_size
+        self.show_legend = show_legend
+        self.legend_position = legend_position
+        self.show_data_labels = show_data_labels
+        self.grid_lines = grid_lines
+        self.style_id = style_id
+
+def create_chart_in_sheet(
+    filepath: str,
+    sheet_name: str,
+    data_range: str,
+    chart_type: str,
+    target_cell: str,
+    title: str = "",
+    x_axis: str = "",
+    y_axis: str = "",
+    style: Optional[Dict] = None
+) -> dict[str, Any]:
+    """Create chart in sheet with enhanced styling options"""
+    try:
+        wb = load_workbook(filepath)
+        if sheet_name not in wb.sheetnames:
+            logger.error(f"Sheet '{sheet_name}' not found")
+            raise ValidationError(f"Sheet '{sheet_name}' not found")
+
+        worksheet = wb[sheet_name]
+
+        # Initialize collections if they don't exist
+        if not hasattr(worksheet, '_drawings'):
+            worksheet._drawings = []
+        if not hasattr(worksheet, '_charts'):
+            worksheet._charts = []
+
+        # Parse the data range
+        if "!" in data_range:
+            range_sheet_name, cell_range = data_range.split("!")
+            if range_sheet_name not in wb.sheetnames:
+                logger.error(f"Sheet '{range_sheet_name}' referenced in data range not found")
+                raise ValidationError(f"Sheet '{range_sheet_name}' referenced in data range not found")
+        else:
+            cell_range = data_range
+
+        try:
+            start_cell, end_cell = cell_range.split(":")
+            start_row, start_col, end_row, end_col = parse_cell_range(start_cell, end_cell)
+        except ValueError as e:
+            logger.error(f"Invalid data range format: {e}")
+            raise ValidationError(f"Invalid data range format: {str(e)}")
+
+        # Validate chart type
+        chart_classes = {
+            "line": LineChart,
+            "bar": BarChart,
+            "pie": PieChart,
+            "scatter": ScatterChart,
+            "area": AreaChart
+        }
+        
+        chart_type_lower = chart_type.lower()
+        ChartClass = chart_classes.get(chart_type_lower)
+        if not ChartClass:
+            logger.error(f"Unsupported chart type: {chart_type}")
+            raise ValidationError(
+                f"Unsupported chart type: {chart_type}. "
+                f"Supported types: {', '.join(chart_classes.keys())}"
+            )
+            
+        chart = ChartClass()
+        
+        # Basic chart settings
+        chart.title = title
+        if hasattr(chart, "x_axis"):
+            chart.x_axis.title = x_axis
+        if hasattr(chart, "y_axis"):
+            chart.y_axis.title = y_axis
+
+        try:
+            # Create data references
+            if chart_type_lower == "scatter":
+                # For scatter charts, create series for each pair of columns
+                for col in range(start_col + 1, end_col + 1):
+                    x_values = Reference(
+                        worksheet,
+                        min_row=start_row + 1,
+                        max_row=end_row,
+                        min_col=start_col
+                    )
+                    y_values = Reference(
+                        worksheet,
+                        min_row=start_row + 1,
+                        max_row=end_row,
+                        min_col=col
+                    )
+                    series = Series(y_values, x_values, title_from_data=True)
+                    chart.series.append(series)
+            else:
+                # For other chart types
+                data = Reference(
+                    worksheet,
+                    min_row=start_row,
+                    max_row=end_row,
+                    min_col=start_col + 1,
+                    max_col=end_col
+                )
+                cats = Reference(
+                    worksheet,
+                    min_row=start_row + 1,
+                    max_row=end_row,
+                    min_col=start_col
+                )
+                chart.add_data(data, titles_from_data=True)
+                chart.set_categories(cats)
+        except Exception as e:
+            logger.error(f"Failed to create chart data references: {e}")
+            raise ChartError(f"Failed to create chart data references: {str(e)}")
+
+        # Apply style if provided
+        try:
+            if style:
+                if style.get("show_legend", True):
+                    chart.legend = Legend()
+                    chart.legend.position = style.get("legend_position", "r")
+                else:
+                    chart.legend = None
+
+                if style.get("show_data_labels", False):
+                    chart.dataLabels = DataLabelList()
+                    chart.dataLabels.showVal = True
+
+                if style.get("grid_lines", False):
+                    if hasattr(chart, "x_axis"):
+                        chart.x_axis.majorGridlines = ChartLines()
+                    if hasattr(chart, "y_axis"):
+                        chart.y_axis.majorGridlines = ChartLines()
+        except Exception as e:
+            logger.error(f"Failed to apply chart style: {e}")
+            raise ChartError(f"Failed to apply chart style: {str(e)}")
+
+        # Set chart size
+        chart.width = 15
+        chart.height = 7.5
+
+        # Create drawing and anchor
+        try:
+            drawing = SpreadsheetDrawing()
+            drawing.chart = chart
+
+            # Validate target cell format
+            if not target_cell or not any(c.isalpha() for c in target_cell) or not any(c.isdigit() for c in target_cell):
+                raise ValidationError(f"Invalid target cell format: {target_cell}")
+
+            # Create anchor
+            col = column_index_from_string(target_cell[0]) - 1
+            row = int(target_cell[1:]) - 1
+            anchor = OneCellAnchor()
+            anchor._from = AnchorMarker(col=col, row=row)
+            drawing.anchor = anchor
+
+            # Add to worksheet
+            worksheet._drawings.append(drawing)
+            worksheet._charts.append(chart)
+        except ValueError as e:
+            logger.error(f"Invalid target cell: {e}")
+            raise ValidationError(f"Invalid target cell: {str(e)}")
+        except Exception as e:
+            logger.error(f"Failed to create chart drawing: {e}")
+            raise ChartError(f"Failed to create chart drawing: {str(e)}")
+
+        try:
+            wb.save(filepath)
+        except Exception as e:
+            logger.error(f"Failed to save workbook: {e}")
+            raise ChartError(f"Failed to save workbook with chart: {str(e)}")
+
+        return {
+            "message": f"{chart_type.capitalize()} chart created successfully",
+            "details": {
+                "type": chart_type,
+                "location": target_cell,
+                "data_range": data_range
+            }
+        }
+        
+    except (ValidationError, ChartError):
+        raise
+    except Exception as e:
+        logger.error(f"Unexpected error creating chart: {e}")
+        raise ChartError(f"Unexpected error creating chart: {str(e)}")