Excel MCP Server

Instructions

Implementation Reference

• src/handlers/file-operations.ts:171-238 (handler)

  The core handler function that implements the write_multi_sheet tool. It creates an Excel workbook with multiple sheets, adds data and headers to each sheet, applies formulas to specified cells, and writes the file to disk.

  async writeMultiSheet(args: ToolArgs): Promise<ToolResponse> {
    const { filePath, sheets, sheetReferences = true } = args;
    const ext = path.extname(filePath).toLowerCase();
    const absolutePath = path.resolve(filePath);
  
    if (ext !== '.xlsx' && ext !== '.xls') {
      throw new Error('write_multi_sheet only works with Excel files (.xlsx or .xls)');
    }
  
    const workbook = new ExcelJS.Workbook();
    const sheetInfo: any[] = [];
  
    // First pass: Create all sheets with data
    for (const sheetDef of sheets) {
      const { name, data, headers, formulas } = sheetDef;
  
      // Prepare data with headers if provided
      const fullData = headers ? [headers, ...data] : data;
  
      // Create worksheet
      const worksheet = workbook.addWorksheet(name);
  
      // Add data to worksheet
      fullData.forEach((row: any[]) => {
        worksheet.addRow(row);
      });
  
      // Apply formulas if provided
      if (formulas && Array.isArray(formulas)) {
        for (const formulaDef of formulas) {
          const { cell, formula } = formulaDef;
  
          // Set formula in worksheet
          const excelCell = worksheet.getCell(cell);
          // If the formula starts with =, remove it for ExcelJS
          const cleanFormula = formula.startsWith('=') ? formula.substring(1) : formula;
          excelCell.value = { formula: cleanFormula };
        }
      }
  
      sheetInfo.push({
        name,
        rowCount: fullData.length,
        columnCount: (fullData.length > 0 && fullData[0]) ? fullData[0].length : 0,
        formulaCount: formulas?.length || 0,
      });
    }
  
    // Write the workbook
    await workbook.xlsx.writeFile(absolutePath);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            filePath: absolutePath,
            mode: 'multi-sheet-advanced',
            sheetsCreated: sheets.length,
            sheetReferences: sheetReferences,
            sheets: sheetInfo,
            totalFormulas: sheetInfo.reduce((sum, sheet) => sum + sheet.formulaCount, 0),
          }, null, 2),
        },
      ],
    };
  }

• src/index.ts:632-694 (schema)

  The input schema definition for the write_multi_sheet tool, specifying parameters like filePath, sheets (with data, headers, formulas), and sheetReferences.

    name: 'write_multi_sheet',
    description: 'Create a complex Excel file with multiple sheets, formulas, and inter-sheet references',
    inputSchema: {
      type: 'object',
      properties: {
        filePath: {
          type: 'string',
          description: 'Path for the new Excel file (must end with .xlsx or .xls)',
        },
        sheets: {
          type: 'array',
          description: 'Array of sheet definitions',
          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',
                },
              },
              formulas: {
                type: 'array',
                description: 'Array of formula definitions',
                items: {
                  type: 'object',
                  properties: {
                    cell: {
                      type: 'string',
                      description: 'Cell address in A1 notation (e.g., "A1", "B5")',
                    },
                    formula: {
                      type: 'string',
                      description: 'Excel formula (e.g., "=SUM(A1:A10)", "=Sheet1!A1+Sheet2!B2")',
                    },
                  },
                  required: ['cell', 'formula'],
                },
              },
            },
            required: ['name', 'data'],
          },
        },
        sheetReferences: {
          type: 'boolean',
          description: 'Enable inter-sheet formula references (default: true)',
        },
      },
      required: ['filePath', 'sheets'],
    },
  },

• src/index.ts:1247-1248 (registration)

  The switch case in the CallToolRequestSchema handler that routes calls to 'write_multi_sheet' to the FileOperationsHandler.writeMultiSheet method.

  case 'write_multi_sheet':
    return await this.fileOpsHandler.writeMultiSheet(toolArgs);

• src/index.ts:55-55 (registration)

  Instantiation of the FileOperationsHandler class instance used for file operations tools including write_multi_sheet.

  this.fileOpsHandler = new FileOperationsHandler();

• src/index.ts:15-15 (registration)

  Import of the FileOperationsHandler class containing the writeMultiSheet method.

  import { FileOperationsHandler } from './handlers/file-operations';