upnorthmedia/ScreenshotMCP

Screenshot MCP

A Model Context Protocol MCP server for capturing website screenshots with full page, element, and device size features.

Features

• Full-page screenshot capture with automatic scrolling
• Element-specific screenshots using CSS selectors
• Multiple device presets (mobile, tablet, desktop)
• Custom viewport configurations
• Advanced wait conditions (CSS selectors, network idle, custom delays)
• Error handling and validation for secure operation
• Rate limiting to prevent resource exhaustion

Installation

1. Clone or download this project
2. Move to the directory: cd /path/to/ScreenshotMCP
3. rename .env.example to .env
4. Install dependencies: npm install
5. Start Server: npm start

Using with Claude Code

You can use Screenshot MCP directly within the Claude Code CLI or Claude Desktop to capture screenshots as part of your development workflow.

For Claude Code CLI: Add to your ~/.config/claude/mcp_servers.json:

{
  "screenshot-full-page-mcp": {
    "command": "node",
    "args": ["/path/to/screenshot-full-page-mcp/index.js"]
  }
}

or

claude mcp add screenshot-full-page-mcp node ./index.js

For Claude Desktop: Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "screenshot-full-page-mcp": {
      "command": "node",
      "args": ["/path/to/screenshot-full-page-mcp/index.js"]
    }
  }
}

Using with Cursor

You can use Screenshot MCP directly within the Cursor IDE to capture screenshots as part of your development workflow.

1. Open Cursor.

2. Go to Settings > MCP Servers.

3. Add a new MCP server entry for Screenshot MCP:

   {
     "mcpServers": {
       "screenshot-full-page-mcp": {
         "command": "node",
         "args": ["/path/to/screenshot-full-page-mcp/index.js"]
       }
     }
   }
   

4. Save your settings.

Usage

Once configured, you can use natural language commands with Claude Code:

Basic Screenshot

"Take a screenshot of https://example.com"

Mobile Screenshot

"Capture a mobile screenshot of https://myapp.com"

Custom Viewport

"Screenshot https://myapp.com at 1024x768 resolution"

Wait for Element

"Take a screenshot of https://example.com after the loading spinner disappears"

Element Screenshot

"Capture just the navigation bar from https://example.com"

Available Tools

capture_screenshot

Captures a full-page screenshot with advanced configuration options.

Parameters:

• url (required): The webpage URL to screenshot
• viewport: Viewport configuration
  • preset: Device preset (mobile, tablet, desktop)
  • width: Custom width in pixels (100-5000)
  • height: Custom height in pixels (100-5000)
  • deviceScaleFactor: Scale factor (0.1-3)
  • isMobile: Mobile device emulation
  • hasTouch: Touch support emulation
• waitFor: Wait conditions
  • type: selector, function, timeout, or networkidle
  • value: CSS selector, function, or timeout value
  • timeout: Wait timeout in milliseconds
• delay: Additional delay before screenshot
• waitUntil: Navigation completion condition

capture_element

Captures a screenshot of a specific page element.

Parameters:

• url (required): The webpage URL
• selector (required): CSS selector for the target element
• viewport: Viewport configuration (same as above)

list_device_presets

Lists all available device presets with their configurations.

Device Presets

Configuration

Environment variables can be set in the .env file:

# Browser Configuration
BROWSER_HEADLESS=true
BROWSER_TIMEOUT=30000
MAX_CONCURRENT_SCREENSHOTS=5

# Screenshot Defaults
DEFAULT_VIEWPORT_WIDTH=1920
DEFAULT_VIEWPORT_HEIGHT=1080
DEFAULT_WAIT_TIMEOUT=10000

# Security
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW=60000

# Debug
DEBUG=false
LOG_LEVEL=info

Security Features

• URL validation (HTTP/HTTPS only)
• CSS selector sanitization
• Rate limiting for concurrent requests
• Sandboxed browser execution
• Input validation and error handling

System Requirements

• Node.js 18+
• Chrome/Chromium browser (installed automatically with Puppeteer)
• Minimum 2GB RAM
• 500MB disk space

Troubleshooting

Common Issues

1. Browser launch fails:

   • Ensure sufficient system resources
   • Check if Chrome/Chromium is properly installed
   • Try setting BROWSER_HEADLESS=false for debugging

2. Screenshot timeout:

   • Increase BROWSER_TIMEOUT in .env
   • Check if the target website loads properly
   • Use appropriate waitUntil conditions

3. Memory issues:

   • Reduce MAX_CONCURRENT_SCREENSHOTS
   • Restart the MCP server periodically
   • Monitor system memory usage

Debug Mode

Enable debug mode by setting DEBUG=true in .env file for detailed logging.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

• Open an issue on GitHub
• Check the troubleshooting section
• Review the MCP documentation