Excel MCP Server

Instructions

Implementation Reference

• src/handlers/file-operations.ts:9-111 (handler)

  Core handler function that executes write_file tool: supports writing to CSV/Excel (.xlsx/.xls), single-sheet with data/headers/sheet, multi-sheet with sheets array using ExcelJS.

  async writeFile(args: ToolArgs): Promise<ToolResponse> {
    const { filePath, data, headers, sheet = 'Sheet1', sheets } = args;
    const ext = path.extname(filePath).toLowerCase();
    const absolutePath = path.resolve(filePath);
  
    // Multi-sheet mode for Excel files
    if (sheets && Array.isArray(sheets)) {
      if (ext === '.csv') {
        throw new Error('CSV format does not support multiple sheets. Use .xlsx or .xls for multi-sheet files.');
      }
  
      if (ext !== '.xlsx' && ext !== '.xls') {
        throw new Error('Multi-sheet mode only works with Excel files (.xlsx or .xls)');
      }
  
      const workbook = new ExcelJS.Workbook();
      let totalRows = 0;
      let totalColumns = 0;
  
      for (const sheetData of sheets) {
        if (!sheetData.data || !Array.isArray(sheetData.data)) {
          throw new Error(`Sheet "${sheetData.name}" must have valid data array`);
        }
  
        const fullData = sheetData.headers
          ? [sheetData.headers, ...sheetData.data]
          : sheetData.data;
  
        if (fullData.length === 0) {
          // Add empty row if no data
          fullData.push([]);
        }
  
        const worksheet = workbook.addWorksheet(sheetData.name);
        fullData.forEach((row: any[]) => {
          worksheet.addRow(row);
        });
  
        totalRows += fullData.length;
        if (fullData.length > 0 && Array.isArray(fullData[0])) {
          totalColumns = Math.max(totalColumns, fullData[0].length || 0);
        }
      }
  
      await workbook.xlsx.writeFile(absolutePath);
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              success: true,
              filePath: absolutePath,
              mode: 'multi-sheet',
              sheetsWritten: sheets.length,
              sheetNames: sheets.map(s => s.name),
              totalRowsWritten: totalRows,
              maxColumnsWritten: totalColumns,
            }, null, 2),
          },
        ],
      };
    }
  
    // Single sheet mode (backward compatible)
    if (!data || !Array.isArray(data)) {
      throw new Error('Either "data" (for single sheet) or "sheets" (for multiple sheets) must be provided.');
    }
  
    const fullData = headers ? [headers, ...data] : data;
  
    if (ext === '.csv') {
      // Write CSV file
      const csvContent = csvStringify.stringify(fullData);
      await fs.writeFile(absolutePath, csvContent, 'utf-8');
    } else if (ext === '.xlsx' || ext === '.xls') {
      // Write Excel file
      const workbook = new ExcelJS.Workbook();
      const worksheet = workbook.addWorksheet(sheet);
      fullData.forEach((row: any[]) => {
        worksheet.addRow(row);
      });
      await workbook.xlsx.writeFile(absolutePath);
    } else {
      throw new Error('Unsupported file format. Please use .csv, .xlsx, or .xls extension.');
    }
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            filePath: absolutePath,
            mode: 'single-sheet',
            sheetName: ext === '.csv' ? null : sheet,
            rowsWritten: fullData.length,
            columnsWritten: fullData[0]?.length || 0,
          }, null, 2),
        },
      ],
    };
  }

• src/index.ts:536-593 (schema)

  Input schema definition for write_file tool in the MCP tools list, specifying parameters like filePath (required), data, headers, sheet, and optional sheets for multi-sheet Excel files.

  name: 'write_file',
  description: 'Write data to a new CSV or Excel file (supports multiple sheets for Excel)',
  inputSchema: {
    type: 'object',
    properties: {
      filePath: {
        type: 'string',
        description: 'Path for the new file (must end with .csv, .xlsx, or .xls)',
      },
      data: {
        type: 'array',
        description: 'Array of arrays representing rows of data (single sheet mode)',
        items: {
          type: 'array',
        },
      },
      headers: {
        type: 'array',
        description: 'Optional headers for the first row (single sheet mode)',
        items: {
          type: 'string',
        },
      },
      sheet: {
        type: 'string',
        description: 'Sheet name for Excel files (single sheet mode, defaults to "Sheet1")',
      },
      sheets: {
        type: 'array',
        description: 'Array of sheet objects for multi-sheet Excel files',
        items: {
          type: 'object',
          properties: {
            name: {
              type: 'string',
              description: 'Sheet name',
            },
            data: {
              type: 'array',
              description: 'Array of arrays representing rows of data',
              items: {
                type: 'array',
              },
            },
            headers: {
              type: 'array',
              description: 'Optional headers for the first row',
              items: {
                type: 'string',
              },
            },
          },
          required: ['name', 'data'],
        },
      },
    },
    required: ['filePath'],
  },

• src/index.ts:1242-1255 (registration)

  Tool registration in MCP server: imports FileOperationsHandler, instantiates it (line 55), lists schema in ListToolsRequestHandler (536-593), and dispatches calls to fileOpsHandler.writeFile in CallToolRequestSchema switch.

  // File Operations
  case 'write_file':
    return await this.fileOpsHandler.writeFile(toolArgs);
  case 'add_sheet':
    return await this.fileOpsHandler.addSheet(toolArgs);
  case 'write_multi_sheet':
    return await this.fileOpsHandler.writeMultiSheet(toolArgs);
  case 'export_analysis':
    return await this.fileOpsHandler.exportAnalysis(toolArgs);
  case 'format_cells':
    return await this.fileOpsHandler.formatCells(toolArgs);
  case 'auto_fit_columns':
    return await this.fileOpsHandler.autoFitColumns(toolArgs);