Screenshot MCP Gateway

A unified MCP (Model Context Protocol) server that combines screenshot capture capabilities with HTTP/SSE gateway functionality for remote access. This project integrates HTTP-ScreenShotMCP with Supergateway to provide a single deployable solution for remote screenshot services.

Features

• ✅ Full-page screenshot capture with Puppeteer
• ✅ Element-specific screenshots using CSS selectors
• ✅ Device viewport presets (mobile, tablet, desktop)
• ✅ Custom viewport configurations
• ✅ Advanced wait conditions (selector, function, timeout, networkidle)
• ✅ HTTP/SSE transport for remote access
• ✅ CORS support for cross-origin requests
• ✅ Headless browser operation (perfect for server deployments)
• ✅ Automatic Chrome installation for headless environments

Quick Start

Installation

npm install

This will automatically:

1. Install all dependencies
2. Download and configure Chromium for headless operation
3. Build the TypeScript source

Running the Server

npm start

The server will start on port 3000 (or the port specified in PORT environment variable).

Endpoints:

• SSE MCP endpoint: http://localhost:3000/sse
• Health check: http://localhost:3000/health

Configuration

Copy .env.example to .env and customize:

cp .env.example .env

Environment Variables:

• PORT: Server port (default: 3000)
• BROWSER_HEADLESS: Run browser in headless mode (default: true)
• BROWSER_TIMEOUT: Browser timeout in milliseconds (default: 30000)
• MAX_CONCURRENT_SCREENSHOTS: Maximum concurrent screenshots (default: 5)

Available MCP Tools

1. capture_screenshot

Capture a full-page screenshot of a webpage with advanced options.

Parameters:

• url (required): The URL of the webpage to screenshot
• viewport (optional): Viewport configuration
  • preset: Device preset (mobile, tablet, desktop)
  • width: Viewport width in pixels
  • height: Viewport height in pixels
  • deviceScaleFactor: Device scale factor
  • isMobile: Whether to emulate mobile device
  • hasTouch: Whether device has touch support
• waitFor (optional): Wait condition before taking screenshot
  • type: Type of wait condition (selector, function, timeout, networkidle)
  • value: Value for wait condition
  • timeout: Timeout in milliseconds
  • idleTime: Network idle time in milliseconds
• standardDelay (optional): Apply standard 2.5s delay after networkidle2 (default: true)
• delay (optional): Additional delay in milliseconds
• waitUntil (optional): When to consider navigation complete (default: networkidle2)

2. capture_element

Capture a screenshot of a specific element on a webpage.

Parameters:

• url (required): The URL of the webpage
• selector (required): CSS selector for the element to capture
• viewport (optional): Viewport configuration
• standardDelay (optional): Apply standard 2.5s delay (default: true)

3. list_device_presets

List available device presets with their configurations.

No parameters required.

Usage with MCP Clients

Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "screenshot": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "http://localhost:3000/sse"
      ]
    }
  }
}

Remote Access

To expose your screenshot server publicly, use ngrok:

# Terminal 1: Start the screenshot server
npm start

# Terminal 2: Expose via ngrok
ngrok http 3000

Then use the ngrok URL in your MCP client configuration:

{
  "mcpServers": {
    "screenshot": {
      "command": "npx",
      "args": [
        "-y",
        "supergateway",
        "--sse",
        "https://your-ngrok-url.ngrok-free.app/sse"
      ]
    }
  }
}

Deployment

Standard Deployment

1. Clone this repository
2. Install dependencies: npm install
3. Build the project: npm run build
4. Set environment variables (create .env from .env.example)
5. Start the server: npm start

Docker Deployment

Create a Dockerfile:

FROM node:18

# Install dependencies for Puppeteer headless Chrome
RUN apt-get update && apt-get install -y \
    chromium \
    chromium-sandbox \
    fonts-liberation \
    libappindicator3-1 \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libcups2 \
    libdbus-1-3 \
    libgdk-pixbuf2.0-0 \
    libnspr4 \
    libnss3 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    xdg-utils \
    --no-install-recommends \
    && rm -rf /var/lib/apt/lists/*

WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies
RUN npm install

# Copy source code
COPY . .

# Build TypeScript
RUN npm run build

# Set environment variables for headless Chrome
ENV PUPPETEER_SKIP_DOWNLOAD=true
ENV PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium
ENV BROWSER_HEADLESS=true

EXPOSE 3000

CMD ["npm", "start"]

Build and run:

docker build -t screenshot-mcp-gateway .
docker run -p 3000:3000 screenshot-mcp-gateway

Headless Server Requirements

For headless server deployments (Ubuntu/Debian):

# Install Chrome dependencies
sudo apt-get update
sudo apt-get install -y \
    chromium-browser \
    chromium-codecs-ffmpeg \
    fonts-liberation \
    libappindicator3-1 \
    libasound2 \
    libatk-bridge2.0-0 \
    libatk1.0-0 \
    libcups2 \
    libdbus-1-3 \
    libgdk-pixbuf2.0-0 \
    libnspr4 \
    libnss3 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    xdg-utils

Development

Build

npm run build

Development Mode (with auto-reload)

npm run dev

Clean Build Artifacts

npm run clean

Architecture

This project combines:

• Screenshot MCP Server: Provides screenshot capture functionality using Puppeteer
• Supergateway Pattern: HTTP/SSE transport layer for remote MCP access
• Express.js: Web server framework
• MCP SDK: Official Model Context Protocol SDK
• Puppeteer: Headless Chrome automation

Security Considerations

• The server is exposed on the network when running in HTTP mode
• Consider implementing authentication for production deployments
• Use environment variables for sensitive configuration
• Implement rate limiting for production use
• Be cautious with URL inputs to prevent SSRF attacks

Troubleshooting

Chrome Installation Issues

If Chrome fails to install automatically:

npx puppeteer browsers install chrome

Headless Mode Issues

If screenshots fail in headless mode, try:

1. Set BROWSER_HEADLESS=false for debugging
2. Check Chrome dependencies are installed
3. Verify Chrome executable path

Connection Issues

• Ensure the port is not already in use
• Check firewall settings for the specified port
• Verify CORS settings if accessing from web clients

License

MIT

Credits

This project integrates:

• HTTP-ScreenShotMCP
• Supergateway