adibirzu/mcp-screenshot-server

Generic MCP Screenshot Server

A Model Context Protocol (MCP) server that provides automated screenshot capabilities for any website.

Features

• 🖼️ Universal Screenshots: Capture any website by providing a URL
• 📁 Application Organization: Automatically organize screenshots by application (Oracle Cloud, AWS, Azure, etc.)
• 🔐 Authenticated Sessions: Support for cookies, localStorage, sessionStorage, and custom headers
• 👁️ Image Viewing: Screenshots are automatically displayed in Claude/ChatGPT responses
• 📱 Batch Processing: Take screenshots of multiple websites at once
• ✨ Smart Annotations: Add arrows, circles, rectangles, and text overlays
• 📖 Documentation Generation: Create HTML guides with all screenshots
• 🎯 High Quality: Full HD (1920x1080) PNG screenshots with timestamps
• ⚡ Fast & Reliable: Uses Puppeteer for consistent browser automation

Tools Available

1. take_screenshot

Capture any website with custom settings.

Parameters:

• url - Complete URL (e.g., "https://example.com", "http://localhost:3000")
• filename - Output filename without extension
• width/height - Viewport dimensions (default: 1920x1080)
• waitForSelector - CSS selector to wait for before capturing
• delay - Additional delay in milliseconds

2. take_multiple_screenshots

Automatically capture multiple websites.

Parameters:

• urls - Array of URL objects with url, filename, and optional waitForSelector

3. annotate_screenshot

Add visual annotations to existing screenshots.

Parameters:

• filename - Screenshot to annotate
• annotations - Array of annotation objects (arrows, circles, rectangles, text)

4. list_screenshots

List all screenshots organized by application.

Parameters:

• appName - Filter by specific application (optional)
• limit - Maximum screenshots to return (default: 50)

5. view_screenshot

View a specific screenshot by filename.

Parameters:

• filename - Screenshot filename (with or without .png extension)
• appName - Application folder name (optional)

6. extract_session_data

Extract session data from a URL for authenticated screenshots.

Parameters:

• url - URL to extract session data from
• includeStorage - Include localStorage and sessionStorage (default: true)

7. connect_to_browser

Connect to an existing browser instance with remote debugging.

Parameters:

• port - Browser remote debugging port (default: 9222)
• url - Browser URL to connect to

8. create_screenshot_guide

Generate an HTML guide with all screenshots.

Parameters:

• title - Guide title
• outputFile - HTML filename

Installation

1. Install Dependencies:

   npm install
   

2. Build the Server:

   npm run build
   

3. Configure Claude Desktop: Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

   {
     "mcpServers": {
       "generic-screenshot": {
         "command": "node",
         "args": ["/Users/abirzu/dev/mcp-screenshot-server/dist/index.js"],
         "env": {}
       }
     }
   }
   

4. Restart Claude Desktop to load the MCP server.

Usage Examples

Basic Screenshot

Take a screenshot of https://cloud.oracle.com/loganalytics/explorer

Authenticated Screenshot

Take a screenshot of https://cloud.oracle.com/dashboard with session data from my browser

Multiple Websites

Take screenshots of these websites: https://cloud.oracle.com, https://console.aws.amazon.com, https://portal.azure.com

List Screenshots

List all my Oracle Cloud screenshots

View Screenshot

Show me the latest Oracle Cloud screenshot

Local Development Server

Take a screenshot of http://localhost:3000/dashboard

Annotated Screenshots

Take a screenshot of https://news.ycombinator.com and add arrows pointing to the top stories

Documentation Generation

Create a screenshot guide with all the captured images

Requirements

• Node.js 18+
• Internet connection for accessing websites
• Claude Desktop with MCP support

Project Structure

mcp-screenshot-server/
├── src/
│   └── index.ts           # Main MCP server implementation
├── dist/                  # Compiled JavaScript
├── screenshots/           # Generated screenshots
├── package.json
├── tsconfig.json
└── README.md

Development

# Build and run
npm run dev

# Build only
npm run build

# Test server
npm test

Troubleshooting

Common Issues

1. MCP Server Not Loading

   • Check Claude Desktop configuration syntax
   • Verify file paths are correct
   • Restart Claude Desktop

2. Screenshots Failing

   • Ensure target website is accessible
   • Check Puppeteer browser permissions
   • Verify network connectivity
   • Use complete URLs with protocol (https:// or http://)

3. Invalid URL Errors

   • Provide complete URLs: https://example.com not example.com
   • Include protocol for local servers: http://localhost:3000

4. No Screenshots Directory

   • Server automatically creates screenshots/ directory
   • Ensure write permissions in project folder

Example URLs

• Public websites: https://www.google.com, https://github.com
• Local development: http://localhost:3000, http://127.0.0.1:8080
• Specific pages: https://example.com/about, http://localhost:3000/dashboard

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

Generic Screenshot Server
Version: 1.0.0
Last Updated: January 2025