Excel MCP Server

Instructions

Implementation Reference

• src/index.ts:307-342 (handler)

  Core handler function that validates the range, loads the Excel workbook and worksheet, parses the range boundaries, iterates over the cells to collect values into a 2D array, and returns a formatted JSON string of the values.

  async function getRangeValues(filePath: string, sheetName: string, range: string): Promise<string> {
    try {
      validateRangeAddress(range);
      
      const workbook = await loadWorkbook(filePath);
      const worksheet = workbook.getWorksheet(sheetName);
      if (!worksheet) {
        throw new Error(`ワークシート '${sheetName}' が見つかりません。利用可能なシート: ${getSheetNames(workbook)}`);
      }
      
      const rangeCells = worksheet.getCell(range);
      const values: any[][] = [];
      
      // 指定範囲のデータを取得する正しい実装
      const [startCell, endCell] = range.split(':');
      const startCellObj = worksheet.getCell(startCell);
      const endCellObj = worksheet.getCell(endCell);
      
      const startRow = Number(startCellObj.row);
      const startCol = Number(startCellObj.col);
      const endRow = Number(endCellObj.row);
      const endCol = Number(endCellObj.col);
      
      for (let row = startRow; row <= endRow; row++) {
        const rowValues: any[] = [];
        for (let col = startCol; col <= endCol; col++) {
          rowValues.push(worksheet.getCell(row, col).value);
        }
        values.push(rowValues);
      }
      
      return `範囲 ${range} の値:\n${JSON.stringify(values, null, 2)}`;
    } catch (error) {
      throw new McpError(ErrorCode.InternalError, `範囲値取得エラー: ${error}`);
    }
  }

• src/index.ts:50-54 (schema)

  Zod schema defining the input parameters for the get_range_values tool: filePath (absolute path to Excel file), sheetName (worksheet name), range (cell range like A1:C3).

  const GetRangeValuesSchema = z.object({
    filePath: z.string().describe("対象のExcelファイルの絶対パス"),
    sheetName: z.string().describe("対象のワークシート名"),
    range: z.string().describe("取得する範囲。A1:C3形式で指定（例: A1:C10, B2:D5）"),
  });

• src/index.ts:551-554 (registration)

  Tool registration in the toolImplementations map: parses input arguments using the schema and delegates to the core getRangeValues handler function.

  get_range_values: async (args: any) => {
    const { filePath, sheetName, range } = GetRangeValuesSchema.parse(args);
    return await getRangeValues(filePath, sheetName, range);
  },

• src/index.ts:496-500 (registration)

  Tool declaration in the list of available tools for ListToolsRequestSchema, including name, description, and JSON schema derived from Zod schema.

  {
    name: "get_range_values",
    description: "指定された範囲のデータを取得します",
    inputSchema: zodToJsonSchema(GetRangeValuesSchema)
  },

• src/index.ts:120-125 (helper)

  Helper function to validate the format of the range string (e.g., A1:C3) using a regex pattern. Called at the start of the handler.

  function validateRangeAddress(range: string): void {
    const rangePattern = /^[A-Z]+[1-9]\d*:[A-Z]+[1-9]\d*$/;
    if (!rangePattern.test(range)) {
      throw new Error(`無効な範囲指定: '${range}'。正しい形式: A1:C3, B2:D10など`);
    }
  }