Dynamic Excel MCP Server

动态Excel MCP服务器

使用模型上下文协议（MCP）的动态Excel文件生成服务器。此服务器允许LLM通过动态JSON模式自动创建具有任何结构的Excel文件。

🚀 特性

• ✅ 从JSON模式生成Excel文件
• ✅ 双重运输方式：本地（stdio）和远程（HTTP/SSE）
• ✅ 随时随地部署：VPS、云（AWS、GCP、Heroku）、Docker
• ✅ 多张纸支持
• ✅ 高级格式（样式、边框、颜色）
• ✅ 数据验证和条件格式化
• ✅ 公式和计算
• ✅ 图表支持（有限）
• ✅ 页面设置和打印选项
• ✅ S3和本地文件存储
• ✅ 用于安全下载的预签名URL
• ✅ 冻结窗格，自动过滤
• ✅ 合并单元格和行分组
• ✅ API密钥验证
• ✅ web客户端的CORS支持

📦 安装

npm install
npm run build

⚙️ 配置

创建一个 .env 文件（复制自 .env.example):

对于本地（标准）模式：

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

对于远程（HTTP/SSE）模式：

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

🔧 用法

🖥️ 本地模式（标准）-适用于Claude桌面

添加到您的Claude Desktop或MCP客户端配置中：

适用于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"
      }
    }
  }
}

适用于 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"
      }
    }
  }
}

🌐 远程模式（HTTP/SSE）-用于Web应用程序和远程访问

启动服务器：

# 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

服务器终结点：

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

客户端使用示例：

看 examples/client-example.ts 使用MCP SDK的完整TypeScript客户端示例。

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.md Dockerfile和docker编写示例
• ☁️ 云：部署到AWS、GCP、Heroku等。
• 🖧 虚拟专用服务器：使用PM2、systemd或其他流程管理器
• 🔒 生产：启用API密钥验证，配置CORS，使用HTTPS

📚 完整部署指南：参见 部署.md

工具：generate_excel

服务器提供了一个工具： generate_excel

输入架构：

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

📚 JSON模式结构

列配置

{
  "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"}
    }
  }
}

支持的列类型

• text：纯文本
• number：数值
• currency：货币格式
• percentage：百分比格式
• date：日期格式
• datetime：日期和时间格式
• boolean：布尔值
• formula：Excel公式

格式选项

{
  "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
  }
}

📖 例子

1.简单数据表

请参阅： examples/01-simple-table.json

创建具有以下格式的基本产品表：

• 冻结窗格
• 自动过滤器
• 货币格式

2.财务报告

请参阅： examples/02-financial-report.json

高级报告包括：

• 带标题的报告布局
• 条件化格式
• 百分比计算
• 公式总计

3.员工数据库

请参阅： examples/03-employee-database.json

员工管理电子表格，包括：

• 多种列类型
• 日期格式
• 货币显示
• 自动过滤器

4.多页报告

请参阅： examples/04-multi-sheet-report.json

综合报告，包括：

• 多张纸
• 摘要和详细视图
• 交叉表一致性

🔨 发展

# 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

🧪 MCP检验员测试

使用MCP检查器测试服务器：

npx @modelcontextprotocol/inspector node build/index.js

🎯 用例

1. 数据导出：将数据库查询导出到格式化的Excel文件
2. 财务报告：生成季度/年度财务报表
3. 库存管理：创建产品目录和库存报告
4. 人力资源管理：员工数据库和工资单报告
5. 销售分析：带有图表和条件格式的销售报告
6. 项目跟踪：多页项目状态报告

🏗️ 建筑

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

🔐 安全说明

• 对于S3存储，确保IAM权限正确
• 使用预签名URL进行临时文件访问
• 为下载链接设置适当的过期时间
• 通过Zod模式验证所有用户输入

📝 许可证

麻省理工学院

🤝 贡献

欢迎投稿！请随时提交拉取请求。

📧 支持

有关问题和疑问，请在GitHub上打开问题。

🎉 致谢

内置：

• 模型上下文协议（MCP）
• ExcelJS
• 黄道
• AWS SDK