Screenshot MCP Server

An MCP (Model Context Protocol) server that captures screenshots of localhost URLs using Puppeteer. Use it with Claude to easily capture and manage screenshots of your local development servers.

Features

• 📸 Capture screenshots of any localhost URL
• 🎨 Configurable viewport dimensions
• 📄 Support for full-page screenshots
• ⏱️ Wait for specific selectors before capturing
• 📋 List all captured screenshots
• 💾 Automatic storage in system temp directory
• 🔒 Security: Only localhost URLs accepted

Installation

Quick Setup (Automated)

# Clone the repository
git clone <repository-url>
cd screenshot-mcp

# Run the setup script
./setup.sh

The setup script will:

• Install dependencies
• Build the TypeScript files
• Prompt you to add the server to Claude Code

Manual Setup

# Clone the repository
git clone <repository-url>
cd screenshot-mcp

# Install dependencies
npm install

# Build the TypeScript files
npm run build

# Add to Claude Code (choose one)
# User scope - available across all projects:
claude mcp add screenshot --scope user -- node /path/to/screenshot-mcp/dist/server.js

# Local scope - current project only:
claude mcp add screenshot-local -- node /path/to/screenshot-mcp/dist/server.js

# Verify installation
claude mcp list

Replace /path/to/screenshot-mcp with the actual path where you cloned this repository.

Custom Screenshot Directory

To use a custom directory for storing screenshots:

claude mcp add screenshot --scope user \
  --env SCREENSHOT_DIR=/your/custom/path \
  -- node /path/to/screenshot-mcp/dist/server.js

Usage

Start Claude Code:

claude

Then ask Claude to take screenshots using natural language:

Basic Screenshots

> Take a screenshot of http://localhost:3000
> Screenshot http://localhost:8080

Full Page Screenshots

> Capture a full page screenshot of http://localhost:3000
> Take a full-page screenshot of localhost:8080

Custom Viewport

> Screenshot http://localhost:3000 with 1366x768 viewport
> Take a mobile screenshot at 375x667 of localhost:3000

Wait for Elements

> Screenshot localhost:3000 and wait for the .app-loaded element
> Take a screenshot after the #content element appears

List Screenshots

> List all screenshots
> Show me the screenshots I've taken

Custom Filename

> Screenshot localhost:3000 and save it as homepage

Use Cases

UI Testing

> Start the dev server on port 3000, then screenshot the homepage
> Take before and after screenshots of the header after making it blue

Design Comparison

> Screenshot all pages on localhost:3000, 3001, and 3002
> Compare these screenshots to the Figma designs

Bug Reports

> Screenshot the broken layout at localhost:3000 on mobile view (375x667)

Available Tools

capture_localhost_screenshot

Takes a screenshot of a localhost URL and returns the path to the saved image.

Parameters:

• url (required): The localhost URL to capture (e.g., http://localhost:3000)
• filename (optional): Custom filename for the screenshot (without extension). Defaults to timestamp.
• fullPage (optional, default: false): Whether to capture the full scrollable page or just the viewport
• viewportWidth (optional, default: 1920): Viewport width in pixels
• viewportHeight (optional, default: 1080): Viewport height in pixels
• waitForSelector (optional): CSS selector to wait for before taking screenshot
• waitTime (optional, default: 1000): Time to wait in milliseconds before taking screenshot

Example:

> Take a screenshot of http://localhost:3000 with full page capture

list_screenshots

Lists all screenshots that have been captured.

Parameters: None

Example:

> List all screenshots

Storage Location

Screenshots are stored in:

{system_temp_dir}/claude-screenshots/

On macOS/Linux: typically /tmp/claude-screenshots/ On Windows: typically %TEMP%\claude-screenshots\

Security

This tool only accepts localhost URLs (localhost, 127.0.0.1, 0.0.0.0, [::1]) for security reasons.

Dependencies

• @modelcontextprotocol/sdk: For MCP server implementation
• puppeteer: For browser automation and screenshot capture

Troubleshooting

"Command not found: claude"

Install the Claude Code CLI first from Claude Code documentation.

"Connection closed" error

Rebuild the project:

cd screenshot-mcp
npm run build

Puppeteer installation issues

If Puppeteer fails to download Chromium:

npm install puppeteer --force

Check if server is running

claude mcp list

Should show screenshot or screenshot-local in the list.

Permission errors on screenshots

The tool saves to /tmp/claude-screenshots/ by default. Make sure this directory is writable:

mkdir -p /tmp/claude-screenshots
chmod 755 /tmp/claude-screenshots

Development

Build the TypeScript files:

npm run build

Watch mode for development:

npm run dev

Contributing

Contributions are welcome! Feel free to:

• Report bugs
• Suggest new features
• Submit pull requests

License

MIT