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'], }, },