# negokaz/excel-mcp-server architecture

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

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

## Overview

Excel MCP Server exposes workbook operations as MCP tools over stdio. An MCP client invokes the server, which registers tool handlers; handlers validate requests, access workbook/sheet operations, and return text, structured metadata, or images. The documented capabilities include sheet description and reading, writing values and formulas, sheet creation and copying, tables, formatting, and Windows screen capture. The source excerpts show tool-to-workbook calls and paging/rendering use; backend implementation details are grouped at the supported package path because they were not fully sampled.

Main entry points: [`internal/server/server.go`](https://github.com/negokaz/excel-mcp-server/blob/main/internal/server/server.go) (MCP server), [`internal/excel`](https://github.com/negokaz/excel-mcp-server/tree/main/internal/excel) (Workbook operations), [`internal/tools/excel_read_sheet.go`](https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_read_sheet.go) (Read sheet), [`internal/tools/excel_describe_sheets.go`](https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_describe_sheets.go) (Describe sheets)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["MCP runtime"]
  node_entry["Server entry<br/>[main.go]"]
  node_server["MCP server<br/>[server.go]"]
end

subgraph group_operations["Workbook tools"]
  node_describe["Describe sheets"]
  node_read["Read sheet"]
  node_write["Write sheet"]
  node_create_table["Create table"]
  node_copy_sheet["Copy sheet"]
  node_format["Format range"]
  node_capture["Screen capture"]
end

subgraph group_excel["Excel access"]
  node_workbook_api["Workbook operations"]
  node_pagination["Range paging<br/>[pagination.go]"]
  node_ole_backend["Windows Excel access<br/>[excel_ole.go]"]
end

subgraph group_support["Response support"]
  node_render["HTML rendering<br/>[common.go]"]
  node_tool_errors["Tool errors<br/>[error.go]"]
end

node_client(("MCP client"))
node_workbook_file[("Excel workbook")]

node_client -->|"calls tools"| node_server
node_entry -->|"starts"| node_server
node_server -->|"registers"| node_describe
node_server -->|"registers"| node_read
node_server -->|"registers"| node_write
node_server -->|"registers"| node_create_table
node_server -->|"registers"| node_copy_sheet
node_server -->|"registers"| node_format
node_server -->|"registers on Windows"| node_capture
node_describe -->|"reads workbook"| node_workbook_api
node_read -->|"reads sheet"| node_workbook_api
node_write -->|"writes sheet"| node_workbook_api
node_create_table -->|"creates table"| node_workbook_api
node_copy_sheet -->|"copies sheet"| node_workbook_api
node_format -->|"sets styles"| node_workbook_api
node_capture -->|"captures range"| node_ole_backend
node_read -->|"pages ranges"| node_pagination
node_describe -->|"lists page ranges"| node_pagination
node_capture -->|"pages ranges"| node_pagination
node_read -->|"renders results"| node_render
node_write -->|"renders results"| node_render
node_workbook_api -.->|"reads and writes"| node_workbook_file
node_ole_backend -.->|"edits workbook"| node_workbook_file

click node_entry "https://github.com/negokaz/excel-mcp-server/blob/main/cmd/excel-mcp-server/main.go"
click node_server "https://github.com/negokaz/excel-mcp-server/blob/main/internal/server/server.go"
click node_describe "https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_describe_sheets.go"
click node_read "https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_read_sheet.go"
click node_write "https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_write_to_sheet.go"
click node_create_table "https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_create_table.go"
click node_copy_sheet "https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_copy_sheet.go"
click node_format "https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_format_range.go"
click node_capture "https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_screen_capture.go"
click node_workbook_api "https://github.com/negokaz/excel-mcp-server/tree/main/internal/excel"
click node_pagination "https://github.com/negokaz/excel-mcp-server/blob/main/internal/excel/pagination.go"
click node_ole_backend "https://github.com/negokaz/excel-mcp-server/blob/main/internal/excel/excel_ole.go"
click node_render "https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/common.go"
click node_tool_errors "https://github.com/negokaz/excel-mcp-server/blob/main/internal/mcp/error.go"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_server,node_client toneBlue
class node_describe,node_read,node_write,node_create_table,node_copy_sheet,node_format,node_capture,node_workbook_file toneAmber
class node_workbook_api,node_pagination,node_ole_backend toneMint
class node_render,node_tool_errors toneRose
```

## Components

### MCP runtime

- [Server entry](https://github.com/negokaz/excel-mcp-server/blob/main/cmd/excel-mcp-server/main.go): `cmd/excel-mcp-server/main.go`
- [MCP server](https://github.com/negokaz/excel-mcp-server/blob/main/internal/server/server.go): `internal/server/server.go`

### Workbook tools

- [Describe sheets](https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_describe_sheets.go): `internal/tools/excel_describe_sheets.go`
- [Read sheet](https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_read_sheet.go): `internal/tools/excel_read_sheet.go`
- [Write sheet](https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_write_to_sheet.go): `internal/tools/excel_write_to_sheet.go`
- [Create table](https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_create_table.go): `internal/tools/excel_create_table.go`
- [Copy sheet](https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_copy_sheet.go): `internal/tools/excel_copy_sheet.go`
- [Format range](https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_format_range.go): `internal/tools/excel_format_range.go`
- [Screen capture](https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/excel_screen_capture.go): `internal/tools/excel_screen_capture.go`

### Excel access

- [Workbook operations](https://github.com/negokaz/excel-mcp-server/tree/main/internal/excel): `internal/excel`
- [Range paging](https://github.com/negokaz/excel-mcp-server/blob/main/internal/excel/pagination.go): `internal/excel/pagination.go`
- [Windows Excel access](https://github.com/negokaz/excel-mcp-server/blob/main/internal/excel/excel_ole.go): `internal/excel/excel_ole.go`

### Response support

- [HTML rendering](https://github.com/negokaz/excel-mcp-server/blob/main/internal/tools/common.go): `internal/tools/common.go`
- [Tool errors](https://github.com/negokaz/excel-mcp-server/blob/main/internal/mcp/error.go): `internal/mcp/error.go`

### Other components

- **MCP client**
- **Excel workbook**

## Connections

- MCP client → MCP server: calls tools (evidence: `internal/server/server.go`)
- Server entry → MCP server: starts (evidence: `cmd/excel-mcp-server/main.go`)
- MCP server → Describe sheets: registers (evidence: `internal/server/server.go`)
- MCP server → Read sheet: registers (evidence: `internal/server/server.go`)
- MCP server → Write sheet: registers (evidence: `internal/server/server.go`)
- MCP server → Create table: registers (evidence: `internal/server/server.go`)
- MCP server → Copy sheet: registers (evidence: `internal/server/server.go`)
- MCP server → Format range: registers (evidence: `internal/server/server.go`)
- MCP server → Screen capture: registers on Windows (evidence: `internal/server/server.go`)
- Describe sheets → Workbook operations: reads workbook (evidence: `internal/tools/excel_describe_sheets.go`)
- Read sheet → Workbook operations: reads sheet (evidence: `internal/tools/excel_read_sheet.go`)
- Write sheet → Workbook operations: writes sheet (evidence: `internal/tools/excel_write_to_sheet.go`)
- Create table → Workbook operations: creates table (evidence: `internal/tools/excel_create_table.go`)
- Copy sheet → Workbook operations: copies sheet (evidence: `internal/tools/excel_copy_sheet.go`)
- Format range → Workbook operations: sets styles (evidence: `internal/tools/excel_format_range.go`)
- Screen capture → Windows Excel access: captures range (evidence: `internal/tools/excel_screen_capture.go`)
- Read sheet → Range paging: pages ranges (evidence: `internal/tools/excel_read_sheet.go`)
- Describe sheets → Range paging: lists page ranges (evidence: `internal/tools/excel_describe_sheets.go`)
- Screen capture → Range paging: pages ranges (evidence: `internal/tools/excel_screen_capture.go`)
- Read sheet → HTML rendering: renders results (evidence: `internal/tools/excel_read_sheet.go`)
- Write sheet → HTML rendering: renders results (evidence: `internal/tools/excel_write_to_sheet.go`)
- Workbook operations → Excel workbook: reads and writes
- Windows Excel access → Excel workbook: edits workbook
