# haris-musa/excel-mcp-server architecture

> Architecture diagram of the GitHub repository haris-musa/excel-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/haris-musa/excel-mcp-server
- Repository: https://github.com/haris-musa/excel-mcp-server

## Overview

##### Main Components Identification
- Server Component: This is the central module (src/excel_mcp/server.py) that handles incoming requests, routing, and the SSE transport mechanism.
- Excel Manipulation Tools: These include modules like calculations.py, formatting.py, chart.py, pivot.py, sheet.py, workbook.py, etc. They encapsulate the specific functionalities for working with Excel files.
- Utility & Helper Modules: Additional tools such as cell_utils.py, data.py, validation.py, exceptions.py provide auxiliary functionality like data handling, error management, and common error checks.
- Configuration and Environment: The use of environment variables (e.g., FASTMCP_PORT, EXCEL_FILES_PATH) along with configuration files such as pyproject.toml and uv.lock indicates a runtime configuration mechanism.
- CI/CD Configuration: The presence of the .github/workflows directory including publish.yml hints at automated workflows for publishing or CI/CD tasks.

##### Relationships and Interactions
- The Client (or AI tool) sends a request (e.g., to create or modify a workbook) to the server through a specified endpoint, such as the SSE endpoint.
- The Server processes the request and dispatches it to the appropriate Excel manipulation module (e.g., formatting, pivot generation, or chart creation).
- Utility modules play a supporting role by processing data, validating inputs, or handling exceptions in these operations.
- The server then provides a response back to the client via SSE (or via other configured transports as mentioned for remote hosting).

##### Architectural Patterns and Design Principles
- Modular Design: The project breaks down Excel processing tasks into individual modules, each handling a separate concern (e.g., calculations, chart, pivot). This is an example of separation of concerns.
- Client-Server Architecture: A central server accepts incoming API requests, processes them by delegating tasks to internal modules, and communicates using the SSE protocol.
- Extensibility: The design is set up to interact with external AI tools and other services by simply configuring the environment variables or using a conversion layer (e.g., Supergateway). This makes the server both reusable and flexible.

##### Relevant Technologies and Frameworks
- Python 3.10+: The project uses modern Python as its base.
- uv (a command-line tool likely for virtual environments and runtime commands) is used for installation and running.
- SSE Protocol: Server-Sent Events are used for push-based updates to clients.
- CI/CD with GitHub Actions: Through the .github/workflows configuration.

##### Elements
- Use clear labels for each component, e.g., “Excel MCP Server (API Entry Point)”, “Excel Processing Modules” (with sub-labels like “Calculations”, “Formatting”, “Charting”, etc.), “Utility Modules”, and “Configuration/Environment”.
○ Client/Application Request → Server API Endpoint.
○ Server → Dispatch/Invoke specific Excel manipulation modules.
○ Modules → Return processed results back to the server → Outgoing SSE to client.
○ Server component (e.g., use a rectangle with a bold border).
○ Modules (group them in a cloud or cluster).
- Annotations for the key technical details such as “SSE Protocol”, “Environment Variables (FASTMCP_PORT, EXCEL_FILES_PATH)”, and references to integration guidelines (e.g., AI tool configurations).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Client
    Client["Client/AI Tool"]:::external

    %% Configuration and CI/CD
    Config["Configuration & Environment"]:::config
    CICD["CI/CD (GitHub Actions)"]:::cicd

    %% Server Component
    Server["Excel MCP Server (API Entry Point)"]:::server

    %% Excel Processing Modules
    subgraph "Excel Processing Modules"
        Calc["Calculations"]:::module
        Format["Formatting"]:::module
        Chart["Charting"]:::module
        Pivot["Pivot Tables"]:::module
        Worksheet["Worksheet Management"]:::module
        Workbook["Workbook Handling"]:::module
    end

    %% Utility Modules
    subgraph "Utility Modules"
        CellUtil["Cell Utilities"]:::utility
        DataMod["Data Handling"]:::utility
        ExceptionMod["Exception Management"]:::utility
        ValidationMod["Validation"]:::utility
    end

    %% Data Flow
    Client -->|"APIRequest"| Server
    Server -->|"dispatch"| Calc
    Server -->|"dispatch"| Format
    Server -->|"dispatch"| Chart
    Server -->|"dispatch"| Pivot
    Server -->|"dispatch"| Worksheet
    Server -->|"dispatch"| Workbook
    Calc -->|"validate"| ValidationMod
    Format -->|"validate"| ValidationMod
    Chart -->|"validate"| ValidationMod
    Pivot -->|"validate"| ValidationMod
    Worksheet -->|"access"| CellUtil
    Workbook -->|"access"| DataMod
    Server -->|"SSE_Response"| Client
    Config -->|"configures"| Server
    CICD -->|"CI_BuildDeploy"| Server

    %% Click Events
    click Server "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/server.py"
    click Calc "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/calculations.py"
    click Format "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/formatting.py"
    click Chart "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/chart.py"
    click Pivot "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/pivot.py"
    click Worksheet "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/sheet.py"
    click Workbook "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/workbook.py"
    click CellUtil "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/cell_utils.py"
    click DataMod "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/data.py"
    click ExceptionMod "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/exceptions.py"
    click ValidationMod "https://github.com/haris-musa/excel-mcp-server/blob/main/src/excel_mcp/validation.py"
    click Config "https://github.com/haris-musa/excel-mcp-server/blob/main/pyproject.toml"
    click CICD "https://github.com/haris-musa/excel-mcp-server/blob/main/.github/workflows/publish.yml"

    %% Styles
    classDef external fill:#FFCC00,stroke:#333,stroke-width:2px;
    classDef server fill:#66CCFF,stroke:#333,stroke-width:2px;
    classDef module fill:#99FF99,stroke:#333,stroke-width:2px;
    classDef utility fill:#FF9966,stroke:#333,stroke-width:2px;
    classDef config fill:#FF99FF,stroke:#333,stroke-width:2px;
    classDef cicd fill:#CCCCFF,stroke:#333,stroke-width:2px;
```
