scroll
Automate page scrolling in any direction within a browser using Puppeteer MCP Server. Control scroll amount, target specific elements, and enable smooth scrolling for automated browser interactions.
Instructions
Scroll the page or a specific element
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| direction | No | down | |
| amount | No | Scroll amount in pixels | |
| selector | No | Element to scroll (scrolls page if not specified) | |
| smooth | No | Use smooth scrolling | |
| tabId | No | Tab ID to operate on (uses active tab if not specified) |
Implementation Reference
- src/tools/input.ts:103-184 (registration)Registers the 'scroll' tool on the MCP server, including the inline asynchronous handler function that handles scrolling logic for page or specific element.server.tool( 'scroll', 'Scroll the page or a specific element', scrollSchema.shape, async ({ direction, amount, selector, smooth, tabId }) => { const pageResult = await getPageForOperation(tabId); if (!pageResult.success) { return handleResult(pageResult); } const page = pageResult.data; const scrollDirection = (direction ?? 'down') as ScrollDirection; const scrollAmount = amount ?? 100; const useSmooth = smooth ?? true; try { // Calculate scroll deltas let deltaX = 0; let deltaY = 0; switch (scrollDirection) { case 'up': deltaY = -scrollAmount; break; case 'down': deltaY = scrollAmount; break; case 'left': deltaX = -scrollAmount; break; case 'right': deltaX = scrollAmount; break; } if (selector) { // Scroll specific element const element = await page.$(selector); if (!element) { return handleResult(err(selectorNotFound(selector))); } await element.evaluate( (el, dx, dy, smoothScroll) => { el.scrollBy({ left: dx, top: dy, behavior: smoothScroll ? 'smooth' : 'auto', }); }, deltaX, deltaY, useSmooth ); } else { // Scroll page await page.evaluate( (dx, dy, smoothScroll) => { window.scrollBy({ left: dx, top: dy, behavior: smoothScroll ? 'smooth' : 'auto', }); }, deltaX, deltaY, useSmooth ); } return handleResult(ok({ scrolled: true, direction: scrollDirection, amount: scrollAmount, selector, })); } catch (error) { return handleResult(err(normalizeError(error))); } } );
- src/tools/input.ts:107-183 (handler)The core handler function for the scroll tool. It retrieves the page, calculates scroll deltas based on direction and amount, and performs scrollBy on either a specific element or the window using Puppeteer evaluate.async ({ direction, amount, selector, smooth, tabId }) => { const pageResult = await getPageForOperation(tabId); if (!pageResult.success) { return handleResult(pageResult); } const page = pageResult.data; const scrollDirection = (direction ?? 'down') as ScrollDirection; const scrollAmount = amount ?? 100; const useSmooth = smooth ?? true; try { // Calculate scroll deltas let deltaX = 0; let deltaY = 0; switch (scrollDirection) { case 'up': deltaY = -scrollAmount; break; case 'down': deltaY = scrollAmount; break; case 'left': deltaX = -scrollAmount; break; case 'right': deltaX = scrollAmount; break; } if (selector) { // Scroll specific element const element = await page.$(selector); if (!element) { return handleResult(err(selectorNotFound(selector))); } await element.evaluate( (el, dx, dy, smoothScroll) => { el.scrollBy({ left: dx, top: dy, behavior: smoothScroll ? 'smooth' : 'auto', }); }, deltaX, deltaY, useSmooth ); } else { // Scroll page await page.evaluate( (dx, dy, smoothScroll) => { window.scrollBy({ left: dx, top: dy, behavior: smoothScroll ? 'smooth' : 'auto', }); }, deltaX, deltaY, useSmooth ); } return handleResult(ok({ scrolled: true, direction: scrollDirection, amount: scrollAmount, selector, })); } catch (error) { return handleResult(err(normalizeError(error))); } }
- src/schemas.ts:102-108 (schema)Zod schema defining the input parameters for the scroll tool, including direction, amount, selector, smooth, and tabId.export const scrollSchema = z.object({ direction: z.enum(['up', 'down', 'left', 'right']).optional().default('down'), amount: z.number().int().min(1).optional().default(100).describe('Scroll amount in pixels'), selector: z.string().optional().describe('Element to scroll (scrolls page if not specified)'), smooth: z.boolean().optional().default(true).describe('Use smooth scrolling'), tabId: tabIdSchema, });
- src/types.ts:149-152 (helper)Type definition for ScrollDirection used in the scroll tool handler and schema./** * Scroll direction */ export type ScrollDirection = 'up' | 'down' | 'left' | 'right';
- src/server.ts:29-29 (registration)Calls registerInputTools to register the input tools group, including scroll, on the main MCP server instance.registerInputTools(server);