MCP Browser Screenshot Server

Instructions

Implementation Reference

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

  Handler for the screenshot_capture tool: captures screenshot of the current page or a specific element, supports fullPage, selector, and format (base64/binary). Uses Puppeteer page.screenshot() or element.screenshot().

  case 'screenshot_capture': {
    const { page } = await ensureBrowser();
    const fullPage = args?.fullPage === true;
    const selector = args?.selector as string | undefined;
    const format = (args?.format as string) || 'base64';
  
    let screenshot: Buffer;
  
    if (selector) {
      const element = await page.$(selector);
      if (!element) {
        throw new McpError(
          ErrorCode.InvalidParams,
          `Element with selector "${selector}" not found`,
        );
      }
      screenshot = (await element.screenshot()) as Buffer;
    } else {
      screenshot = (await page.screenshot({ fullPage })) as Buffer;
    }
  
    if (format === 'base64') {
      return {
        content: [
          {
            type: 'text',
            text: `data:image/png;base64,${screenshot.toString('base64')}`,
          },
        ],
      };
    } else {
      return {
        content: [
          {
            type: 'text',
            text: 'Screenshot captured as binary data',
          },
        ],
      };
    }
  }

• src/index.ts:141-163 (schema)

  Schema definition for screenshot_capture tool, defining input parameters: fullPage (boolean), selector (string), format (enum: base64/binary).

    name: 'screenshot_capture',
    description: 'Take a screenshot of the current page',
    inputSchema: {
      type: 'object',
      properties: {
        fullPage: {
          type: 'boolean',
          description: 'Capture full page screenshot',
          default: false,
        },
        selector: {
          type: 'string',
          description: 'CSS selector of element to screenshot',
        },
        format: {
          type: 'string',
          enum: ['base64', 'binary'],
          description: 'Output format for the screenshot',
          default: 'base64',
        },
      },
    },
  },

• src/index.ts:90-207 (registration)

  Registration of all tools including screenshot_capture in the ListToolsRequestSchema handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        {
          name: 'browser_launch',
          description: 'Launch a new browser instance',
          inputSchema: {
            type: 'object',
            properties: {
              headless: {
                type: 'boolean',
                description: 'Run browser in headless mode',
                default: true,
              },
            },
          },
        },
        {
          name: 'browser_navigate',
          description: 'Navigate to a URL',
          inputSchema: {
            type: 'object',
            properties: {
              url: {
                type: 'string',
                description: 'URL to navigate to',
              },
              waitUntil: {
                type: 'string',
                enum: [
                  'load',
                  'domcontentloaded',
                  'networkidle0',
                  'networkidle2',
                ],
                description: 'When to consider navigation complete',
                default: 'networkidle2',
              },
            },
            required: ['url'],
          },
        },
        {
          name: 'browser_close',
          description: 'Close the browser instance',
          inputSchema: {
            type: 'object',
            properties: {},
          },
        },
        {
          name: 'screenshot_capture',
          description: 'Take a screenshot of the current page',
          inputSchema: {
            type: 'object',
            properties: {
              fullPage: {
                type: 'boolean',
                description: 'Capture full page screenshot',
                default: false,
              },
              selector: {
                type: 'string',
                description: 'CSS selector of element to screenshot',
              },
              format: {
                type: 'string',
                enum: ['base64', 'binary'],
                description: 'Output format for the screenshot',
                default: 'base64',
              },
            },
          },
        },
        {
          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,
              },
            },
          },
        },
        {
          name: 'browser_execute_script',
          description: 'Execute JavaScript in the browser context',
          inputSchema: {
            type: 'object',
            properties: {
              script: {
                type: 'string',
                description: 'JavaScript code to execute',
              },
            },
            required: ['script'],
          },
        },
      ],
    };
  });

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

  Helper function ensureBrowser() that launches Puppeteer browser and page if not available, used by screenshot_capture 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,
    };
  }