Excel MCP Server

Instructions

Implementation Reference

• src/handlers/file-operations.ts:292-419 (handler)

  The primary handler function for the format_cells tool. It loads an Excel workbook, parses the specified range using A1 notation, applies comprehensive cell styling including font properties, fill, borders, alignment, and number formatting to each cell in the range, then saves the modified workbook and returns a success response with details.
  async formatCells(args: ToolArgs): Promise<ToolResponse> { const { filePath, range, styling, sheet } = args; const ext = path.extname(filePath).toLowerCase(); const absolutePath = path.resolve(filePath); if (ext !== '.xlsx' && ext !== '.xls') { throw new Error('Cell formatting 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); // Get the worksheet const worksheet = sheet ? workbook.getWorksheet(sheet) : workbook.getWorksheet(1); if (!worksheet) { throw new Error(`Sheet "${sheet || 'first sheet'}" not found`); } // Parse range (e.g., "A1:C5" or "B2") let startCell: { row: number; col: number }; let endCell: { row: number; col: number }; if (range.includes(':')) { const [start, end] = range.split(':'); const startParsed = parseA1Notation(start); const endParsed = parseA1Notation(end); // Convert to 1-based indexing for ExcelJS startCell = { row: startParsed.row + 1, col: startParsed.col + 1 }; endCell = { row: endParsed.row + 1, col: endParsed.col + 1 }; } else { const parsed = parseA1Notation(range); // Convert to 1-based indexing for ExcelJS startCell = endCell = { row: parsed.row + 1, col: parsed.col + 1 }; } let formattedCells = 0; // Apply formatting to the range for (let row = startCell.row; row <= endCell.row; row++) { for (let col = startCell.col; col <= endCell.col; col++) { const cell = worksheet.getCell(row, col); // Apply font styling if (styling.font) { const fontStyle: any = {}; if (styling.font.bold !== undefined) fontStyle.bold = styling.font.bold; if (styling.font.italic !== undefined) fontStyle.italic = styling.font.italic; if (styling.font.underline !== undefined) fontStyle.underline = styling.font.underline; if (styling.font.size !== undefined) fontStyle.size = styling.font.size; if (styling.font.color !== undefined) fontStyle.color = { argb: styling.font.color }; if (styling.font.name !== undefined) fontStyle.name = styling.font.name; cell.font = { ...cell.font, ...fontStyle }; } // Apply fill (background color) if (styling.fill) { if (styling.fill.color) { cell.fill = { type: 'pattern', pattern: styling.fill.pattern || 'solid', fgColor: { argb: styling.fill.color } }; } } // Apply borders if (styling.border) { const borderStyle: any = {}; const borderConfig = { style: styling.border.style || 'thin', color: { argb: styling.border.color || 'FF000000' } }; if (styling.border.top !== false) borderStyle.top = borderConfig; if (styling.border.bottom !== false) borderStyle.bottom = borderConfig; if (styling.border.left !== false) borderStyle.left = borderConfig; if (styling.border.right !== false) borderStyle.right = borderConfig; cell.border = { ...cell.border, ...borderStyle }; } // Apply alignment if (styling.alignment) { const alignmentStyle: any = {}; if (styling.alignment.horizontal) alignmentStyle.horizontal = styling.alignment.horizontal; if (styling.alignment.vertical) alignmentStyle.vertical = styling.alignment.vertical; if (styling.alignment.wrapText !== undefined) alignmentStyle.wrapText = styling.alignment.wrapText; if (styling.alignment.textRotation !== undefined) alignmentStyle.textRotation = styling.alignment.textRotation; cell.alignment = { ...cell.alignment, ...alignmentStyle }; } // Apply number format if (styling.numberFormat) { cell.numFmt = styling.numberFormat; } formattedCells++; } } // Save the workbook await workbook.xlsx.writeFile(absolutePath); return { content: [ { type: 'text', text: JSON.stringify({ success: true, filePath: absolutePath, sheetName: worksheet.name, range, cellsFormatted: formattedCells, stylingApplied: Object.keys(styling), }, null, 2), }, ], }; }
• src/utils/file-utils.ts:7-20 (helper)

  Utility function parseA1Notation converts A1 cell notation (e.g., 'A1', 'C5') to zero-based {row, col} coordinates. Critically used in formatCells to parse start/end ranges for applying formatting.
  export function parseA1Notation(a1: string): CellAddress { const match = a1.match(/^([A-Z]+)(\d+)$/); if (!match) { throw new Error(`Invalid A1 notation: ${a1}`); } const col = match[1].split('').reduce((acc, char) => { return acc * 26 + char.charCodeAt(0) - 'A'.charCodeAt(0) + 1; }, 0) - 1; const row = parseInt(match[2]) - 1; return { row, col }; }