MCP Browser Screenshot Server

Instructions

Implementation Reference

• src/index.ts:309-337 (handler)

  Handler for the screenshot_viewport tool: sets the page viewport using provided preset or custom dimensions, then captures and returns a base64-encoded PNG screenshot.

  case 'screenshot_viewport': {
    const { page } = await ensureBrowser();
    const preset = args?.preset as string | undefined;
    const width = args?.width as number | undefined;
    const height = args?.height as number | undefined;
    const fullPage = args?.fullPage === true;
  
    if (preset && viewportPresets[preset]) {
      await page.setViewport(viewportPresets[preset]);
    } else if (width && height) {
      await page.setViewport({ width, height });
    } else {
      throw new McpError(
        ErrorCode.InvalidParams,
        'Either preset or width/height must be provided',
      );
    }
  
    const screenshot = (await page.screenshot({ fullPage })) as Buffer;
  
    return {
      content: [
        {
          type: 'text',
          text: `data:image/png;base64,${screenshot.toString('base64')}`,
        },
      ],
    };
  }

• src/index.ts:164-190 (registration)

  Registration of the screenshot_viewport tool in the list of available tools, including name, description, and input schema.

  {
    name: 'screenshot_viewport',
    description: 'Take a screenshot with specific viewport settings',
    inputSchema: {
      type: 'object',
      properties: {
        preset: {
          type: 'string',
          enum: ['mobile', 'tablet', 'desktop', 'laptop'],
          description: 'Viewport preset to use',
        },
        width: {
          type: 'number',
          description: 'Custom viewport width',
        },
        height: {
          type: 'number',
          description: 'Custom viewport height',
        },
        fullPage: {
          type: 'boolean',
          description: 'Capture full page screenshot',
          default: false,
        },
      },
    },
  },

• src/index.ts:167-188 (schema)

  Input schema defining parameters for the screenshot_viewport tool: preset, width, height, fullPage.

  inputSchema: {
    type: 'object',
    properties: {
      preset: {
        type: 'string',
        enum: ['mobile', 'tablet', 'desktop', 'laptop'],
        description: 'Viewport preset to use',
      },
      width: {
        type: 'number',
        description: 'Custom viewport width',
      },
      height: {
        type: 'number',
        description: 'Custom viewport height',
      },
      fullPage: {
        type: 'boolean',
        description: 'Capture full page screenshot',
        default: false,
      },
    },

• src/index.ts:31-56 (helper)

  Preset viewport configurations used by the screenshot_viewport handler for common device sizes.

  const viewportPresets: Record<string, ViewportPreset> = {
    mobile: {
      width: 375,
      height: 812,
      deviceScaleFactor: 3,
      isMobile: true,
      hasTouch: true,
    },
    tablet: {
      width: 768,
      height: 1024,
      deviceScaleFactor: 2,
      isMobile: true,
      hasTouch: true,
    },
    desktop: {
      width: 1920,
      height: 1080,
      deviceScaleFactor: 1,
    },
    laptop: {
      width: 1366,
      height: 768,
      deviceScaleFactor: 1,
    },
  };

• src/index.ts:70-88 (helper)

  Utility function to ensure a browser and page instance are available, launching if necessary. Used by screenshot_viewport and other tools.

  async function ensureBrowser(): Promise<{ browser: Browser; page: Page }> {
    if (!browserState.browser || !browserState.browser.isConnected()) {
      const headless = process.env.HEADLESS !== 'false';
      browserState.browser = await puppeteer.launch({
        headless,
        args: ['--no-sandbox', '--disable-setuid-sandbox'],
      });
      browserState.page = await browserState.browser.newPage();
    }
  
    if (!browserState.page || browserState.page.isClosed()) {
      browserState.page = await browserState.browser.newPage();
    }
  
    return {
      browser: browserState.browser,
      page: browserState.page,
    };
  }