MCP Safari Screenshot

🚀 Safari Screenshot Tool

A Node.js MCP server for capturing screenshots using Safari on macOS. This tool allows you to capture screenshots of web pages with various configurations, providing high - quality results similar to native macOS screenshots.

🚀 Quick Start

This tool is a Node.js MCP server that enables you to capture screenshots using Safari on macOS. It offers flexibility in terms of window size, zoom level, and page load waiting time.

✨ Features

• Capture screenshots of windows with specific sizes.
• Support different zoom levels.
• Configurable page load waiting time.
• Clean up after capturing.
• Provide native macOS screenshot quality.

💻 Usage Examples

Basic Usage

import { takeScreenshot } from './screenshot.js';

// Basic window screenshot
await takeScreenshot({
	url: 'https://www.apple.com',
	outputPath: './screenshot.png',
	width: 1024, // Optional: Window width (Default: 1024)
	height: 768, // Optional: Window height (Default: 768)
	waitTime: 3, // Optional: Time to wait for loading (Default: 3 seconds)
	zoomLevel: 1, // Optional: Page zoom level (Default: 1)
});

Advanced Usage

// Test responsive design
await takeScreenshot({
	url: 'https://www.apple.com',
	outputPath: './mobile.png',
	width: 375, // iPhone SE width
	height: 667, // iPhone SE height
	zoomLevel: 1,
});

// High - resolution capture
await takeScreenshot({
	url: 'https://www.apple.com',
	outputPath: './desktop-hd.png',
	width: 1920, // Full HD width
	height: 1080, // Full HD height
	waitTime: 5, // Wait longer to capture HD content
	zoomLevel: 0.8, // Slightly zoom out
});

📦 Installation

npm install safari-screenshot

📚 Documentation

Requirements

• macOS
• Safari
• Node.js >= 14.0.0
• The terminal needs accessibility permissions (System Settings → Security & Privacy → Privacy → Accessibility)

Options

Common Viewport Sizes

This module has been tested for the following common viewport sizes:

• Desktop: 1920×1080 (Full HD)
• Laptop: 1366×768
• Tablet: 1024×768
• Mobile: 375×667

How It Works

1. Discovery

   • The MCP server reports its capabilities to the Cursor agent.
   • Returns the supported tools and parameters.

2. Execute Screenshot

   • When receiving a request of type take_screenshot, the MCP server performs the following steps:
     • Open Safari and set the necessary preferences.
     • Use seleniumWebDriver to control the Safari browser.
     • Wait for the page to load (configurable).
     • Capture the screenshot and save it to the specified location.

Examples

1. Test Discovery

   echo '{"type":"discover"}' | npx -y ./server.js
   

   Expected response:

   {
     "type": "capabilities",
     "tools": [
       {
         "name": "take_screenshot",
         "parameters": ["url", "outputPath", "waitTime", "zoomLevel"]
       }
     ]
   }
   

2. Execute Screenshot

   echo '{"type":"execute","tool":"take_screenshot","input":"Take a screenshot of https://apple.com","requestId":"123"}' | npx -y ./server.js
   

   Expected results:

   • The screenshot is saved to the ./screenshots/ directory.
   • Return the result via the requestId.

Troubleshooting

If you encounter issues:

1. Check if the terminal has accessibility permissions.
2. Ensure that Safari is not in private browsing mode.
3. Ensure that the working directory is writable.
4. Check the error messages in the Cursor console.

📄 License

MIT

Local Testing

You can directly test the MCP implementation:

# Test discovery
echo '{"type":"discover"}' | npx -y ./server.js

# Test screenshot
echo '{"type":"execute","tool":"take_screenshot","input":"Take a screenshot of https://apple.com","requestId":"123"}' | npx -y ./server.js

Expected responses:

1. Discovery will return capabilities.
2. Execution will:
   • Log progress to stderr.
   • Return the result JSON to stdout.
   • Save the screenshot to ./screenshots/