Dynamic Excel MCP Server

Dynamic Excel file generation server using Model Context Protocol (MCP). This server allows LLMs to automatically create Excel files with any structure through dynamic JSON schemas.

🚀 Features

✅ Generate Excel files from JSON schemas
✅ Dual transport modes: Local (stdio) and Remote (HTTP/SSE)
✅ Deploy anywhere: VPS, Cloud (AWS, GCP, Heroku), Docker
✅ Multiple sheets support
✅ Advanced formatting (styling, borders, colors)
✅ Data validation and conditional formatting
✅ Formulas and calculations
✅ Charts support (limited)
✅ Page setup and printing options
✅ S3 and local file storage
✅ Presigned URLs for secure downloads
✅ Freeze panes, auto-filter
✅ Merged cells and row grouping
✅ API key authentication
✅ CORS support for web clients

📦 Installation

npm install npm run build

⚙️ Configuration

Create a .env file (copy from .env.example):

For Local (Stdio) Mode:

TRANSPORT_MODE=stdio # Local MCP client mode STORAGE_TYPE=local DEV_STORAGE_PATH=./temp-files LOG_LEVEL=info

For Remote (HTTP/SSE) Mode:

TRANSPORT_MODE=http # Remote server mode HTTP_PORT=3000 HTTP_HOST=0.0.0.0 ALLOWED_ORIGINS=* # Or specific domains: https://app.example.com API_KEY=your-secret-api-key # Optional STORAGE_TYPE=s3 # or 'local' AWS_ACCESS_KEY_ID=your_key AWS_SECRET_ACCESS_KEY=your_secret AWS_REGION=ap-southeast-1 S3_BUCKET=your-bucket PRESIGNED_URL_EXPIRY=3600 LOG_LEVEL=info

🔧 Usage

🖥️ Local Mode (Stdio) - For Claude Desktop

Add to your Claude Desktop or MCP client configuration:

For macOS (~/Library/Application Support/Claude/claude_desktop_config.json):

{ "mcpServers": { "excel-generator": { "command": "node", "args": ["/absolute/path/to/excel-mcp-server/build/index.js"], "env": { "STORAGE_TYPE": "local", "DEV_STORAGE_PATH": "./temp-files", "LOG_LEVEL": "info" } } } }

For Windows (%APPDATA%\Claude\claude_desktop_config.json):

{ "mcpServers": { "excel-generator": { "command": "node", "args": ["C:\\path\\to\\excel-mcp-server\\build\\index.js"], "env": { "STORAGE_TYPE": "local", "DEV_STORAGE_PATH": "./temp-files", "LOG_LEVEL": "info" } } } }

🌐 Remote Mode (HTTP/SSE) - For Web Apps & Remote Access

Start the server:

# Using environment variable TRANSPORT_MODE=http npm start # Or using npm script npm run start:http # Or with .env file configured for http mode npm start

Server endpoints:

http://localhost:3000/health - Health check http://localhost:3000/info - Server information http://localhost:3000/sse - SSE endpoint for MCP clients

Example client usage:

See examples/client-example.ts for a complete TypeScript client example using the MCP SDK.

import { Client } from '@modelcontextprotocol/sdk/client/index.js'; import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'; const transport = new SSEClientTransport( new URL('http://localhost:3000/sse'), { headers: { 'X-API-Key': 'your-api-key' } // If API_KEY is set } ); const client = new Client({ name: 'excel-client', version: '1.0.0', }, { capabilities: {} }); await client.connect(transport); const result = await client.callTool({ name: 'generate_excel', arguments: excelSchema });

Deployment options:

🐳 Docker: See DEPLOYMENT.md for Dockerfile and docker-compose examples
☁️ Cloud: Deploy to AWS, GCP, Heroku, etc.
🖧 VPS: Use PM2, systemd, or other process managers
🔒 Production: Enable API key auth, configure CORS, use HTTPS

📚 Full deployment guide: See DEPLOYMENT.md

Tool: generate_excel

The server provides one tool: generate_excel

Input Schema:

{ "file_name": "report.xlsx", "sheets": [ { "name": "Sheet1", "columns": [...], "data": [...], "formatting": {...} } ], "metadata": {...}, "options": {...} }

📚 JSON Schema Structure

Column Configuration

{ "header": "Column Name", "key": "data_key", "width": 20, "type": "currency", "format": "#,##0₫", "style": { "font": {"bold": true, "size": 12}, "alignment": {"horizontal": "center"}, "fill": { "type": "pattern", "pattern": "solid", "fgColor": {"argb": "FFFF0000"} } } }

Supported Column Types

text: Plain text
number: Numeric values
currency: Currency format
percentage: Percentage format
date: Date format
datetime: Date and time format
boolean: Boolean values
formula: Excel formulas

Formatting Options

{ "freeze_panes": "A2", "auto_filter": true, "conditional_formatting": [ { "range": "A2:A100", "type": "cellIs", "operator": "greaterThan", "formulae": [0], "style": { "fill": { "type": "pattern", "pattern": "solid", "fgColor": {"argb": "FF90EE90"} } } } ], "totals_row": { "column_key": "=SUM(A2:A100)" }, "merged_cells": ["A1:D1"], "row_heights": { "1": 30, "2": 25 } }

📖 Examples

1. Simple Data Table

See: examples/01-simple-table.json

Creates a basic product table with formatting:

Freeze panes
Auto-filter
Currency formatting

2. Financial Report

See: examples/02-financial-report.json

Advanced report with:

Report layout with title
Conditional formatting
Percentage calculations
Formula totals

3. Employee Database

See: examples/03-employee-database.json

Employee management spreadsheet with:

Multiple column types
Date formatting
Currency display
Auto-filter

4. Multi-Sheet Report

See: examples/04-multi-sheet-report.json

Comprehensive report with:

Multiple sheets
Summary and detail views
Cross-sheet consistency

🔨 Development

# Run in development mode (with auto-reload) npm run dev # Build TypeScript npm run build # Start production server npm start # Run tests npm test # Lint code npm run lint

🧪 Testing with MCP Inspector

Test the server using the MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

🎯 Use Cases

Data Export: Export database queries to formatted Excel files
Financial Reports: Generate quarterly/annual financial statements
Inventory Management: Create product catalogs and stock reports
HR Management: Employee databases and payroll reports
Sales Analytics: Sales reports with charts and conditional formatting
Project Tracking: Project status reports with multiple sheets

🏗️ Architecture

src/ ├── index.ts # MCP Server entry point ├── types/ │ └── schema.ts # TypeScript types & Zod schemas ├── generators/ │ ├── base-generator.ts # Abstract base class │ ├── basic-generator.ts # Simple tables │ └── report-generator.ts # Reports with styling ├── formatters/ │ ├── cell-formatter.ts # Cell formatting │ ├── style-formatter.ts # Styling utilities │ └── formula-builder.ts # Formula generation ├── storage/ │ ├── s3-storage.ts # S3 upload handler │ └── local-storage.ts # Local file system ├── validators/ │ └── schema-validator.ts # JSON schema validation └── utils/ ├── logger.ts # Logging utility └── error-handler.ts # Error handling

🔐 Security Notes

For S3 storage, ensure proper IAM permissions
Use presigned URLs for temporary file access
Set appropriate expiry times for download links
Validate all user inputs through Zod schemas

📝 License

MIT

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Support

For issues and questions, please open an issue on GitHub.

🎉 Acknowledgments

Built with:

Dynamic Excel MCP Server

Dynamic Excel MCP Server

🚀 Features

📦 Installation

⚙️ Configuration

🔧 Usage

🖥️ Local Mode (Stdio) - For Claude Desktop

🌐 Remote Mode (HTTP/SSE) - For Web Apps & Remote Access

Tool: generate_excel

📚 JSON Schema Structure

Column Configuration

Supported Column Types

Formatting Options

📖 Examples

1. Simple Data Table

2. Financial Report

3. Employee Database

4. Multi-Sheet Report

🔨 Development

🧪 Testing with MCP Inspector

🎯 Use Cases

🏗️ Architecture

🔐 Security Notes

📝 License

🤝 Contributing

📧 Support

🎉 Acknowledgments

Related Resources

Tools

New MCP Servers

MCP directory API