sheets_update_borders

Modify cell borders in Google Sheets by specifying the spreadsheet ID, range, and border styles. Streamline formatting tasks programmatically with structured input.

Instructions

Update borders of cells in a Google Sheet

Input Schema

TableJSON Schema

Name	Required	Description	Default
`borders`	Yes
`range`	Yes
`spreadsheetId`	Yes

Implementation Reference

src/tools/update-borders.ts:54-134 (handler)

The main handler function that validates input, parses the range, builds the UpdateBordersRequest for the Google Sheets API batchUpdate, converts border properties, and executes the update.

export async function updateBordersHandler(input: any): Promise<ToolResponse> {
  try {
    // Handle case where borders comes as JSON string
    input.borders = parseJsonInput(input.borders, 'borders');

    const validatedInput = updateBordersInputSchema.parse(input) as UpdateBordersInput;
    const sheets = await getAuthenticatedClient();

    // Extract sheet name and get sheet ID
    const { sheetName, range: cleanRange } = extractSheetName(validatedInput.range);
    const sheetId = await getSheetId(sheets, validatedInput.spreadsheetId, sheetName);

    // Parse range to GridRange
    const gridRange = parseRange(cleanRange, sheetId);

    // Build the border update request
    const updateBordersRequest: sheets_v4.Schema$UpdateBordersRequest = {
      range: gridRange,
    };

    // Helper function to convert our border format to Google's format
    const convertBorder = (border?: any): sheets_v4.Schema$Border | undefined => {
      if (!border) {
        return undefined;
      }
      return {
        style: border.style,
        color: border.color,
        width: border.width,
      };
    };

    const topBorder = convertBorder(validatedInput.borders.top);
    if (topBorder) {
      updateBordersRequest.top = topBorder;
    }

    const bottomBorder = convertBorder(validatedInput.borders.bottom);
    if (bottomBorder) {
      updateBordersRequest.bottom = bottomBorder;
    }

    const leftBorder = convertBorder(validatedInput.borders.left);
    if (leftBorder) {
      updateBordersRequest.left = leftBorder;
    }

    const rightBorder = convertBorder(validatedInput.borders.right);
    if (rightBorder) {
      updateBordersRequest.right = rightBorder;
    }

    const innerHorizontalBorder = convertBorder(validatedInput.borders.innerHorizontal);
    if (innerHorizontalBorder) {
      updateBordersRequest.innerHorizontal = innerHorizontalBorder;
    }

    const innerVerticalBorder = convertBorder(validatedInput.borders.innerVertical);
    if (innerVerticalBorder) {
      updateBordersRequest.innerVertical = innerVerticalBorder;
    }

    // Execute the border update
    const response = await sheets.spreadsheets.batchUpdate({
      spreadsheetId: validatedInput.spreadsheetId,
      requestBody: {
        requests: [
          {
            updateBorders: updateBordersRequest,
          },
        ],
      },
    });

    return formatToolResponse(`Successfully updated borders for range ${validatedInput.range}`, {
      spreadsheetId: response.data.spreadsheetId,
    });
  } catch (error) {
    return handleError(error);
  }
}

src/tools/update-borders.ts:11-52 (schema)

Zod schemas for color, border, borders objects, and the main input schema. Also the Tool object definition with name, description, and inputSchema for MCP.

// Schema definitions
const colorSchema = z
  .object({
    red: z.number().min(0).max(1).optional(),
    green: z.number().min(0).max(1).optional(),
    blue: z.number().min(0).max(1).optional(),
    alpha: z.number().min(0).max(1).optional(),
  })
  .optional();

const borderSchema = z
  .object({
    style: z.enum(['NONE', 'SOLID', 'DASHED', 'DOTTED', 'SOLID_MEDIUM', 'SOLID_THICK', 'DOUBLE']),
    color: colorSchema,
    width: z.number().positive().optional(),
  })
  .optional();

const bordersSchema = z.object({
  top: borderSchema,
  bottom: borderSchema,
  left: borderSchema,
  right: borderSchema,
  innerHorizontal: borderSchema,
  innerVertical: borderSchema,
});

const updateBordersInputSchema = z.object({
  spreadsheetId: z.string(),
  range: z.string(),
  borders: bordersSchema,
});

export const updateBordersTool: Tool = {
  name: 'sheets_update_borders',
  description: 'Update borders of cells in a Google Sheet',
  inputSchema: {
    type: 'object',
    properties: updateBordersInputSchema.shape,
    required: ['spreadsheetId', 'range', 'borders'],
  },
};

src/index.ts:32-64 (registration)

Registration of the updateBordersHandler in the toolHandlers Map used by the MCP server to dispatch tool calls.

const toolHandlers = new Map<string, (input: any) => Promise<any>>([
  ['sheets_check_access', tools.handleCheckAccess],
  ['sheets_get_values', tools.handleGetValues],
  ['sheets_batch_get_values', tools.handleBatchGetValues],
  ['sheets_get_metadata', tools.handleGetMetadata],
  ['sheets_update_values', tools.handleUpdateValues],
  ['sheets_batch_update_values', tools.handleBatchUpdateValues],
  ['sheets_append_values', tools.handleAppendValues],
  ['sheets_clear_values', tools.handleClearValues],
  ['sheets_create_spreadsheet', tools.handleCreateSpreadsheet],
  ['sheets_insert_sheet', tools.handleInsertSheet],
  ['sheets_delete_sheet', tools.handleDeleteSheet],
  ['sheets_duplicate_sheet', tools.handleDuplicateSheet],
  ['sheets_copy_to', tools.handleCopyTo],
  ['sheets_update_sheet_properties', tools.handleUpdateSheetProperties],
  ['sheets_format_cells', tools.formatCellsHandler],
  ['sheets_update_borders', tools.updateBordersHandler],
  ['sheets_merge_cells', tools.mergeCellsHandler],
  ['sheets_unmerge_cells', tools.unmergeCellsHandler],
  ['sheets_add_conditional_formatting', tools.addConditionalFormattingHandler],
  // Batch operations
  ['sheets_batch_delete_sheets', tools.handleBatchDeleteSheets],
  ['sheets_batch_format_cells', tools.handleBatchFormatCells],
  // Chart operations
  ['sheets_create_chart', tools.handleCreateChart],
  ['sheets_update_chart', tools.handleUpdateChart],
  ['sheets_delete_chart', tools.handleDeleteChart],
  // Link and date operations
  ['sheets_insert_link', tools.handleInsertLink],
  ['sheets_insert_date', tools.handleInsertDate],
  // Row operations
  ['sheets_insert_rows', tools.handleInsertRows],
]);

src/index.ts:67-99 (registration)

Inclusion of the updateBordersTool in the allTools array returned by ListToolsRequestHandler.

const allTools = [
  tools.checkAccessTool,
  tools.getValuesTool,
  tools.batchGetValuesTool,
  tools.getMetadataTool,
  tools.updateValuesTool,
  tools.batchUpdateValuesTool,
  tools.appendValuesTool,
  tools.clearValuesTool,
  tools.createSpreadsheetTool,
  tools.insertSheetTool,
  tools.deleteSheetTool,
  tools.duplicateSheetTool,
  tools.copyToTool,
  tools.updateSheetPropertiesTool,
  tools.formatCellsTool,
  tools.updateBordersTool,
  tools.mergeCellsTool,
  tools.unmergeCellsTool,
  tools.addConditionalFormattingTool,
  // Batch operations
  tools.batchDeleteSheetsTool,
  tools.batchFormatCellsTool,
  // Chart operations
  tools.createChartTool,
  tools.updateChartTool,
  tools.deleteChartTool,
  // Link and date operations
  tools.insertLinkTool,
  tools.insertDateTool,
  // Row operations
  tools.insertRowsTool,
];

src/tools/index.ts:16-16 (registration)
Re-export of updateBordersTool and updateBordersHandler from the individual tool file to make them available for import in src/index.ts.
```
export * from './update-borders.js';
```

mcp-gsheets