jeremedia/screenshotter_mcp

Screenshotter MCP

A Model Context Protocol (MCP) server that uploads screenshot files to a remote server and returns public URLs for GitHub integration.

Overview

GitHub doesn't allow direct file uploads via API - you need to provide full URLs for images. This MCP server solves that problem by:

1. Taking a screenshot file path as input
2. Uploading the file to a configured remote server
3. Returning a public URL that can be used in GitHub issues, pull requests, etc.

This enables AI assistants like Claude Code to easily share screenshots in GitHub workflows.

Features

• Multiple upload methods: Currently supports SSH/SCP, easily extensible
• Configurable: YAML-based configuration with validation
• Secure: SSH key-based authentication, file type validation
• Flexible naming: Timestamp, UUID, or original filename options
• Error handling: Comprehensive error reporting and validation
• CLI tools: Built-in configuration validation and status checking

Installation

Installing the Ruby Gem

Add this line to your application's Gemfile:

gem 'screenshotter_mcp'

And then execute:

bundle install

Or install it yourself as:

gem install screenshotter_mcp

Installing to Claude Code (Recommended)

The easiest way to use Screenshotter MCP with Claude Code is to use the built-in install command:

# Install for your user (available across all projects)
./bin/screenshotter_mcp cc_install

# Install for current project only (creates .mcp.json)
./bin/screenshotter_mcp cc_install -s project

# Install with custom config file
./bin/screenshotter_mcp cc_install -c /path/to/config.yml

This command automatically:

• Detects your Ruby installation
• Registers the MCP server with Claude Code
• Configures the proper environment variables
• Makes the server immediately available in Claude Code

After installation, you can verify it's working:

claude mcp list

Configuration

Create a configuration file at one of these locations:

1. ./config/screenshotter_mcp.yml (project-specific)
2. ~/.screenshotter_mcp.yml (user-specific)
3. Custom path via SCREENSHOTTER_MCP_CONFIG environment variable

Example Configuration

upload:
  method: ssh
  public_url_base: https://yourdomain.com/screenshots/
  max_file_size: 10485760  # 10MB in bytes
  allowed_types:
    - png
    - jpg
    - jpeg
    - gif
  file_naming: timestamp  # Options: timestamp, uuid, original
  
  ssh:
    host: yourdomain.com
    user: your_username
    remote_path: /var/www/html/screenshots/
    key_path: ~/.ssh/id_rsa
    port: 22

Usage

Starting the MCP Server

screenshotter_mcp start

Validating Configuration

screenshotter_mcp validate

Checking Service Status

screenshotter_mcp status

Using Custom Configuration

screenshotter_mcp -c /path/to/config.yml start

MCP Tools

The server provides four MCP tools:

1. upload_screenshot

Uploads a screenshot file and returns a public URL.

Parameters:

• file_path (required): Path to the screenshot file
• filename (optional): Custom filename override
• file_naming (optional): Naming strategy override

Returns:

{
  "success": true,
  "url": "https://yourdomain.com/screenshots/20231201_143022_screenshot.png",
  "message": "Screenshot uploaded successfully",
  "file_path": "/path/to/screenshot.png",
  "public_url": "https://yourdomain.com/screenshots/20231201_143022_screenshot.png"
}

2. get_upload_status

Checks if the upload service is configured and accessible.

Returns:

{
  "success": true,
  "upload_method": "ssh",
  "public_url_base": "https://yourdomain.com/screenshots/",
  "max_file_size": 10485760,
  "allowed_types": ["png", "jpg", "jpeg", "gif"],
  "file_naming": "timestamp",
  "connection_status": "connected",
  "connection_message": "SSH connection successful"
}

3. validate_config

Validates the current configuration setup.

Returns:

{
  "success": true,
  "message": "Configuration is valid",
  "upload_method": "ssh",
  "checks": [
    {
      "name": "SSH Configuration",
      "status": "passed",
      "message": "SSH configuration is valid"
    },
    {
      "name": "Connection Test",
      "status": "connected",
      "message": "SSH connection successful"
    }
  ]
}

4. take_screenshot

Takes a screenshot using native OS tools (macOS screencapture, Linux gnome-screenshot/scrot, Windows snippingtool).

Parameters:

• type (optional): Screenshot type - "interactive" (default), "window", "screen", "area"
• filename (optional): Custom filename for the screenshot
• delay (optional): Delay in seconds before capture
• window_title (optional): Window title to capture (future feature)
• display (optional): Display number for multi-monitor setups
• clipboard (optional): Copy to clipboard instead of file

Returns:

{
  "success": true,
  "path": "/tmp/screenshot_20231201_143022.png",
  "filename": "screenshot_20231201_143022.png",
  "size": 123456,
  "message": "Screenshot saved to /tmp/screenshot_20231201_143022.png"
}

Development

After checking out the repo, run:

bundle install

To run tests:

bundle exec rspec

To run the linter:

bundle exec rubocop

Contributing

1. Fork it (https://github.com/jeremedia/screenshotter_mcp/fork)
2. Create your feature branch (git checkout -b feature/my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin feature/my-new-feature)
5. Create a new Pull Request

License

The gem is available as open source under the terms of the MIT License.

Security

This tool handles file uploads and SSH connections. Please ensure:

• SSH keys are properly secured
• Remote servers are properly configured
• File upload directories have appropriate permissions
• Only trusted users have access to the configuration