Excel MCP Server

Instructions

Implementation Reference

• src/handlers/file-operations.ts:113-169 (handler)

  The core handler function that implements the add_sheet tool logic: reads an existing Excel file, adds a new worksheet with provided data and optional headers, and saves the updated workbook.

  async addSheet(args: ToolArgs): Promise<ToolResponse> {
    const { filePath, sheetName, data, headers, position } = args;
    const ext = path.extname(filePath).toLowerCase();
    const absolutePath = path.resolve(filePath);
  
    if (ext !== '.xlsx' && ext !== '.xls') {
      throw new Error('add_sheet only works with Excel files (.xlsx or .xls)');
    }
  
    try {
      await fs.access(absolutePath);
    } catch {
      throw new Error(`File not found: ${filePath}`);
    }
  
    // Read existing workbook
    const workbook = new ExcelJS.Workbook();
    await workbook.xlsx.readFile(absolutePath);
  
    // Check if sheet name already exists
    if (workbook.getWorksheet(sheetName)) {
      throw new Error(`Sheet "${sheetName}" already exists in the workbook`);
    }
  
    // Prepare data with headers if provided
    const fullData = headers ? [headers, ...data] : data;
  
    // Create new worksheet
    const worksheet = workbook.addWorksheet(sheetName);
    fullData.forEach((row: any[]) => {
      worksheet.addRow(row);
    });
  
    // Note: ExcelJS doesn't support inserting worksheets at specific positions
    // The worksheet is added at the end of the workbook
  
    // Write the updated workbook
    await workbook.xlsx.writeFile(absolutePath);
  
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify({
            success: true,
            filePath: absolutePath,
            sheetName,
            sheetCount: workbook.worksheets.length,
            sheetNames: workbook.worksheets.map(ws => ws.name),
            rowsAdded: fullData.length,
            columnsAdded: fullData[0]?.length || 0,
            position: position !== undefined ? position : workbook.worksheets.length - 1,
          }, null, 2),
        },
      ],
    };
  }

• src/index.ts:598-629 (schema)

  The JSON schema defining the input parameters for the add_sheet tool, including filePath, sheetName, data, optional headers and position.

  inputSchema: {
    type: 'object',
    properties: {
      filePath: {
        type: 'string',
        description: 'Path to the existing Excel file (.xlsx or .xls)',
      },
      sheetName: {
        type: 'string',
        description: 'Name for the new sheet',
      },
      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',
        },
      },
      position: {
        type: 'number',
        description: 'Position to insert the sheet (0-based index, optional)',
      },
    },
    required: ['filePath', 'sheetName', 'data'],
  },

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

  Registration of the add_sheet tool in the MCP server's CallToolRequestSchema handler, dispatching to FileOperationsHandler.addSheet method.

  return await this.fileOpsHandler.addSheet(toolArgs);

• src/index.ts:596-630 (registration)

  Tool registration in the ListToolsRequestSchema response, defining name, description, and input schema for add_sheet.

    name: 'add_sheet',
    description: 'Add a new sheet to an existing Excel file',
    inputSchema: {
      type: 'object',
      properties: {
        filePath: {
          type: 'string',
          description: 'Path to the existing Excel file (.xlsx or .xls)',
        },
        sheetName: {
          type: 'string',
          description: 'Name for the new sheet',
        },
        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',
          },
        },
        position: {
          type: 'number',
          description: 'Position to insert the sheet (0-based index, optional)',
        },
      },
      required: ['filePath', 'sheetName', 'data'],
    },
  },