MCP Screenshot Server

Instructions

Implementation Reference

• src/index.ts:134-217 (handler)

  The main handler for the 'take_screenshot' tool. Validates input, launches Puppeteer in headless mode, sets viewport if specified, navigates to the URL, generates a timestamped filename, saves the screenshot (full page optional), and returns the relative path or error message.

    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      if (request.params.name !== 'take_screenshot') {
        throw new McpError(
          ErrorCode.MethodNotFound,
          `Unknown tool: ${request.params.name}`
        );
      }
  
      const options = request.params.arguments as unknown as ScreenshotOptions;
      if (!options?.url) {
        throw new McpError(
          ErrorCode.InvalidParams,
          'URL is required'
        );
      }
      
      try {
        const browser = await puppeteer.launch({
          headless: true,
          args: ['--no-sandbox', '--disable-setuid-sandbox'],
        });
  
        const page = await browser.newPage();
        
        // Set viewport if dimensions provided
        if (options.width && options.height) {
          await page.setViewport({
            width: options.width,
            height: options.height,
          });
        }
  
        // Navigate to URL
        await page.goto(options.url, {
          waitUntil: 'networkidle0',
          timeout: 30000,
        });
  
        // Generate filename with timestamp
        const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
        const filename = `screenshot-${timestamp}.png`;
        
        // If outputPath is provided, ensure it's relative to current working directory
        const outputPath = options.outputPath 
          ? path.join(process.cwd(), options.outputPath)
          : path.join(this.outputDir, filename);
  
        // Ensure output directory exists
        const outputDir = path.dirname(outputPath);
        if (!fs.existsSync(outputDir)) {
          fs.mkdirSync(outputDir, { recursive: true });
        }
  
        // Take screenshot
        await page.screenshot({
          path: outputPath,
          fullPage: options.fullPage || false,
        });
  
        await browser.close();
  
        // Return path relative to current working directory
        const relativePath = path.relative(process.cwd(), outputPath);
        return {
          content: [
            {
              type: 'text',
              text: `Screenshot saved to: ${relativePath}`,
            },
          ],
        };
      } catch (error: any) {
        return {
          content: [
            {
              type: 'text',
              text: `Screenshot error: ${error.message}`,
            },
          ],
          isError: true,
        };
      }
    });
  }

• src/index.ts:35-69 (registration)

  Registration of the 'take_screenshot' tool in the MCP server capabilities, defining name, description, and input schema.

    take_screenshot: {
      name: 'take_screenshot',
      description: 'Capture a screenshot of any web page or local GUI',
      inputSchema: {
        type: 'object',
        properties: {
          url: {
            type: 'string',
            description: 'URL to capture (can be http://, https://, or file:///)',
          },
          width: {
            type: 'number',
            description: 'Viewport width in pixels',
            minimum: 1,
            maximum: 3840,
          },
          height: {
            type: 'number',
            description: 'Viewport height in pixels',
            minimum: 1,
            maximum: 2160,
          },
          fullPage: {
            type: 'boolean',
            description: 'Capture full scrollable page',
          },
          outputPath: {
            type: 'string',
            description: 'Custom output path (optional)',
          },
        },
        required: ['url'],
      },
    },
  },

• src/index.ts:14-20 (schema)

  TypeScript interface defining the ScreenshotOptions used in the tool handler for input validation.

  interface ScreenshotOptions {
    url: string;
    width?: number;
    height?: number;
    fullPage?: boolean;
    outputPath?: string;
  }

• src/index.ts:97-131 (registration)

  Tool schema returned by the ListTools handler.

    {
      name: 'take_screenshot',
      description: 'Capture a screenshot of any web page or local GUI',
      inputSchema: {
        type: 'object',
        properties: {
          url: {
            type: 'string',
            description: 'URL to capture (can be http://, https://, or file:///)',
          },
          width: {
            type: 'number',
            description: 'Viewport width in pixels',
            minimum: 1,
            maximum: 3840,
          },
          height: {
            type: 'number',
            description: 'Viewport height in pixels',
            minimum: 1,
            maximum: 2160,
          },
          fullPage: {
            type: 'boolean',
            description: 'Capture full scrollable page',
          },
          outputPath: {
            type: 'string',
            description: 'Custom output path (optional)',
          },
        },
        required: ['url'],
      },
    },
  ],