dynamic-excel-mcp-server by nam090320251 - MCP Server

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

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: