mcp-screenshots-windows

YossiAshkenazi/mcp-screenshots-windows

3.1

If you are the rightful owner of mcp-screenshots-windows and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server that provides Claude and other AI assistants with seamless access to your Windows screenshots folder.

Tools
3
Resources
0
Prompts
0

MCP Screenshots Windows

npm version License: MIT

A Model Context Protocol (MCP) server that provides Claude and other AI assistants with seamless access to your Windows screenshots folder. No more repeated permission requests!

🌟 Features

  • 🔓 Permanent Access: Configure once, use forever - no repeated permission dialogs
  • 🔍 Smart Detection: Automatically finds screenshots in common Windows locations
  • 📸 Multiple Tools: Three powerful tools for screenshot management
  • 🚀 Multiple Deployment Options: NPX, Docker, or Windows Service
  • 🔒 Secure: Read-only access with validation for all operations
  • 📦 Easy Installation: One-command setup with multiple options

🛠️ Available Tools

get_latest_screenshot

Retrieves the most recently created/modified screenshot.

Parameters:

  • includeContent (boolean): Include base64 content of the image
  • searchAllDirs (boolean): Search all directories or just primary

list_recent_screenshots

Lists recent screenshots with metadata (filename, size, timestamps).

Parameters:

  • limit (number): Maximum screenshots to return (default: 10)
  • searchAllDirs (boolean): Search all directories (default: true)

get_screenshot_by_name

Retrieves a specific screenshot by filename.

Parameters:

  • filename (string): Name of the screenshot file
  • includeContent (boolean): Include base64 content

📂 Monitored Directories

By default, the server monitors:

  • C:\Users\[Username]\Pictures\Screenshots (Primary)
  • C:\Users\[Username]\OneDrive\Pictures\Screenshots
  • C:\Users\[Username]\Pictures
  • C:\Users\[Username]\Desktop
  • C:\Users\[Username]\Downloads

🚀 Installation & Deployment Options

Option 1: NPX (Simplest - Recommended)

The easiest way to use this MCP server is via NPX, which requires no installation:

Claude Desktop Configuration:

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "screenshots": {
      "command": "npx",
      "args": ["-y", "@yossiashkenazi/mcp-screenshots-windows"],
      "env": {
        "WINDOWS_USERNAME": "YourUsername"
      }
    }
  }
}

Then restart Claude Desktop. That's it!

Option 2: Docker (Isolated & Auto-Start)

Docker provides isolation and can auto-start with Windows.

Quick Setup:
# Clone the repository
git clone https://github.com/YossiAshkenazi/mcp-screenshots-windows.git
cd mcp-screenshots-windows

# Build and run with Docker Compose
docker-compose up -d
Configure Claude Desktop:

Add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "screenshots": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "C:/Users/YourUsername/Pictures:/screenshots/Pictures:ro",
        "-v", "C:/Users/YourUsername/Desktop:/screenshots/Desktop:ro",
        "mcp-screenshots-windows:latest"
      ]
    }
  }
}
Enable Auto-Start with Windows:
# Set Docker Desktop to start with Windows
# In Docker Desktop: Settings → General → Start Docker Desktop when you sign in

# The container will auto-restart due to "restart: unless-stopped" in docker-compose.yml

Option 3: Windows Service (Native Auto-Start)

For a native Windows service that starts automatically:

Using NSSM (Non-Sucking Service Manager):

  1. Download NSSM: https://nssm.cc/download

  2. Install the service:

# Build the project first
npm install
npm run build

# Install as Windows service
nssm install MCPScreenshots "C:\Program Files\nodejs\node.exe"
nssm set MCPScreenshots AppParameters "C:\path\to\mcp-screenshots-windows\build\index.js"
nssm set MCPScreenshots AppDirectory "C:\path\to\mcp-screenshots-windows"
nssm set MCPScreenshots DisplayName "MCP Screenshots Server"
nssm set MCPScreenshots Description "MCP server for Windows screenshots access"
nssm set MCPScreenshots Start SERVICE_AUTO_START
  1. Start the service:
nssm start MCPScreenshots
Using Task Scheduler:
  1. Open Task Scheduler
  2. Create Basic Task → Name: "MCP Screenshots Server"
  3. Trigger: "When the computer starts"
  4. Action: Start a program
  5. Program: node.exe
  6. Arguments: C:\path\to\mcp-screenshots-windows\build\index.js
  7. Start in: C:\path\to\mcp-screenshots-windows

Option 4: PM2 (Process Manager)

PM2 keeps your server running and can start with Windows:

# Install PM2 globally
npm install -g pm2

# Start the server
pm2 start build/index.js --name mcp-screenshots

# Save current process list
pm2 save

# Enable startup with Windows
pm2 startup
# Follow the instructions provided by PM2

# View logs
pm2 logs mcp-screenshots

Option 5: Local Installation

For development or manual control:

# Clone and install
git clone https://github.com/YossiAshkenazi/mcp-screenshots-windows.git
cd mcp-screenshots-windows
npm install
npm run build

# Run directly
npm start

Configure Claude Desktop with the full path to your installation.

🔧 Configuration

Environment Variables

  • WINDOWS_USERNAME: Override the detected Windows username
  • SCREENSHOT_DIRS: Additional directories to monitor (semicolon-separated)

Example:

"env": {
  "WINDOWS_USERNAME": "JohnDoe",
  "SCREENSHOT_DIRS": "D:\\Screenshots;E:\\Images\\Captures"
}

🎯 Usage Examples

Once configured, you can ask Claude:

  • "Get the latest screenshot from my computer"
  • "Show me the last 5 screenshots I took"
  • "Find the screenshot named 'example.png'"
  • "Get my latest screenshot with its content" (for base64 data)
  • "List all screenshots from today"

🐛 Troubleshooting

Server Not Appearing in Claude

  1. Ensure Claude Desktop is completely closed
  2. Verify config file: %APPDATA%\Claude\claude_desktop_config.json
  3. Check JSON syntax is valid
  4. For Docker/Service: verify they're running
  5. Restart Claude Desktop

No Screenshots Found

  1. Verify screenshots exist in monitored directories
  2. Check file extensions (.png, .jpg, .jpeg, .gif, .bmp, .webp)
  3. Add custom directories via SCREENSHOT_DIRS environment variable

Permission Errors

  • For local installation: Run as Administrator if needed
  • For Docker: Ensure volume mounts are correct
  • For Service: Check service account permissions

🏗️ Development

# Install dependencies
npm install

# Development with auto-rebuild
npm run watch

# Build
npm run build

# Run tests (when available)
npm test

📝 Publishing to NPM

# Login to npm
npm login

# Bump version
npm version patch|minor|major

# Publish
npm publish --access public

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📄 License

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

🙏 Acknowledgments

📧 Support

For issues, questions, or suggestions, please open an issue on GitHub.

Made with ❤️ for the Claude community