WSLSnapit-MCP 📸

WSLSnapit-MCP is a powerful Model Context Protocol (MCP) server that provides advanced screenshot capture and clipboard reading capabilities for Windows applications from within WSL environments. It enables AI assistants to capture screens, windows, and monitors with intelligent image processing and optimization, as well as read text and images from the Windows clipboard.

✨ Features

📸 Screenshot Capture

Monitor Selection: Capture all monitors, primary monitor, or specific monitor by number
Window Targeting: Capture specific windows by title (partial match) or process name
Smart Compression: Automatic image optimization to stay under 1MB with progressive quality adjustment
Direct Return: Images can be returned directly to AI assistants or saved to disk
DPI-Aware: Handles multi-monitor setups with different scaling factors correctly

📋 Clipboard Reading

Auto-Detection: Automatically detects whether clipboard contains text or image
Text Support: Read text content from Windows clipboard
Image Support: Capture images from clipboard with automatic compression
Format Control: Force specific format (text/image) or use auto mode

🚀 Performance

Efficient Processing: Memory-conscious handling of high-resolution captures
Progressive Compression: Dynamic quality adjustment (1920px → 1280px → 800px if needed)
Optimized Communication: Base64 encoding for reliable binary data transfer

📦 Installation

Prerequisites

Windows 10/11 with WSL2 installed
Node.js 18.0.0 or higher
npm, yarn, or bun package manager
PowerShell (comes with Windows)

Quick Install

# Clone the repository
git clone https://github.com/yourusername/WSLSnapit-MCP.git
cd WSLSnapit-MCP

# Install dependencies
npm install
# or
yarn install
# or
bun install

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "wslsnapit": {
      "command": "wsl",
      "args": [
        "--cd",
        "/mnt/h/dev/mcp/wslsnapit-mcp",
        "node",
        "index.js"
      ]
    }
  }
}

Note: Adjust the path /mnt/h/dev/mcp/wslsnapit-mcp to match your installation location.

🎯 Usage

Screenshot Capture

The take_screenshot tool supports various capture modes:

Basic Usage

// Capture all monitors (default)
take_screenshot()

// Capture primary monitor only
take_screenshot({ monitor: "primary" })

// Capture specific monitor (1, 2, 3, etc.)
take_screenshot({ monitor: 2 })

Window Capture

// Capture window by title (partial match)
take_screenshot({ windowTitle: "Visual Studio" })

// Capture window by process name
take_screenshot({ processName: "notepad" })

// Handle multiple matching windows
take_screenshot({ windowTitle: "Chrome", windowIndex: 2 })

Output Options

// Return image directly (default)
take_screenshot({ returnDirect: true })

// Save to file
take_screenshot({ 
  returnDirect: false, 
  filename: "myshot.png",
  folder: "/home/user/screenshots" 
})

// Control JPEG quality (for direct return)
take_screenshot({ 
  returnDirect: true, 
  quality: 90 
})

Clipboard Reading

The read_clipboard tool supports both text and image content:

// Auto-detect clipboard content (default)
read_clipboard()

// Force text reading
read_clipboard({ format: "text" })

// Force image reading
read_clipboard({ format: "image" })

🔧 Parameters Reference

take_screenshot

Parameter	Type	Default	Description
`filename`	string	"screenshot.png"	Filename when saving to disk
`monitor`	string\|number	"all"	Monitor selection: "all", "primary", or monitor number
`windowTitle`	string	-	Capture window by title (partial match)
`windowIndex`	number	1	Which window to capture when multiple match
`processName`	string	-	Capture window by process name
`folder`	string	-	Custom folder path (supports WSL and Windows paths)
`returnDirect`	boolean	true	Return image to AI or save to disk
`quality`	number	80	JPEG quality (1-100) for direct return

read_clipboard

Parameter	Type	Default	Description
`format`	string	"auto"	Format: "auto", "text", or "image"

🛡️ Security Considerations

WSLSnapit-MCP is designed with security in mind:

Minimal Permissions: Windows executable runs with minimal permissions, only accessing screen capture and clipboard APIs
Local Processing: All clipboard data is processed locally without any network transmission
Process Isolation: PowerShell runs as a separate Windows process, preventing access to sensitive WSL environment
Input Validation: All user inputs are properly escaped to prevent injection attacks
Resource Limits: Memory limits and progressive compression prevent resource exhaustion

🏗️ Architecture

Core Components

MCP Server: Implements the Model Context Protocol for AI assistant integration
PowerShell Bridge: Executes Windows-specific operations from WSL
Image Processor: Uses Sharp library for efficient image compression
Path Handler: Seamlessly converts between WSL and Windows paths

Technology Stack

Node.js with ES modules
@modelcontextprotocol/sdk for MCP implementation
Sharp for image processing
PowerShell for Windows API integration

🐛 Troubleshooting

Common Issues

"No windows found" error
- Ensure the target window is visible and not minimized
- Try using a shorter or different part of the window title
- Use process name instead of window title
Large screenshots fail to return
- The tool automatically compresses images to stay under 1MB
- If issues persist, try lowering the quality parameter
Clipboard reading returns empty
- Ensure content is properly copied to clipboard
- Try specifying the format explicitly instead of using auto-detect
Path not found errors
- Verify the folder path exists
- Remember WSL paths start with /mnt/c/ for C: drive

Debug Mode

To run with debug output:

DEBUG=* node index.js

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built for use with Claude Desktop and the Model Context Protocol
Image processing powered by Sharp
Thanks to the MCP community for inspiration and support

📞 Support

🐛 Report bugs by opening an issue
💡 Request features through GitHub discussions
📧 Contact: your-email@example.com

Made with ❤️ for the WSL and MCP community

WSLSnapit-MCP