Skip to main content
Glama

CleanShot MCP Server (Unofficial)

Control CleanShot X from any MCP-compatible AI assistant with simple commands like "take a screenshot" or "capture this area".

Built with the Model Context Protocol (MCP) - a standard for connecting AI assistants to external tools. Works with Amp, Claude Desktop, and other MCP-compatible applications.

CleanShot MCP Demo

Requirements

  • macOS

  • CleanShot X installed and running

    • ⚙️ Settings > Advanced > API > ☑️ Allow applications to control CleanShot X

  • Node.js 18+

Related MCP server: Screen View MCP

Quick Start

1. Install the MCP Server

# Option 1: Use without installing (recommended)
npx cleanshot-mcp

# Option 2: Install globally
npm install -g cleanshot-mcp

2. Configure Your MCP Client

Add this to your MCP client configuration:

{
  "amp.mcpServers": {
    "cleanshot": {
      "command": "npx",
      "args": ["cleanshot-mcp"],
      "env": {}
    }
  }
}

3. Start Using It

Simply tell your AI assistant:

  • "Take a fullscreen screenshot and copy it"

  • "Capture this area: x: 100, y: 100, width: 500, height: 300"

  • "Open CleanShot settings"

Examples

Natural Language Commands:

Command

What It Does

"Take a fullscreen screenshot and copy it"

Captures entire screen and copies to clipboard

"Capture this area: x: 100, y: 100, width: 500, height: 300"

Captures specific screen region

"Open CleanShot settings"

Opens CleanShot preferences

"Extract text from this area"

Uses OCR to extract text from screen region

Available Tools

This MCP server provides 17 CleanShot tools including:

  • Screenshots: Area capture, fullscreen, window capture, self-timer

  • Recording: Screen recording with custom areas

  • Text Extraction: OCR from any screen region

  • Annotation: Open annotation tools for images

  • Management: History, settings, desktop icon control

🔧 View Complete Tool List | 📕 API Reference

Development

Building

npm run build

Development Mode

npm run dev

Testing

Make sure CleanShot is installed and running, then test individual commands:

# Test basic functionality
node dist/index.js

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Submit a pull request

Support

IMPORTANT

PleaseDO NOT contact CleanShot support for problems with this MCP server. This is an unofficial integration created by fans of their product.


⭐ Star this repo if you find it useful!

Created with Amp by Sourcegraph

Available Tools

19 tools
cleanshot_add_quick_access_overlayB

Add a file to CleanShot's Quick Access Overlay

Inputs: filepath (required).

cleanshot_all_in_oneC

Launch CleanShot's All-In-One mode with optional position and size parameters

Inputs: x, y, width, height, +1 more.

cleanshot_capture_areaC

Open CleanShot's Capture Area mode with optional parameters

Inputs: x, y, width, action, +2 more.

cleanshot_capture_fullscreenC

Take a fullscreen screenshot

Inputs: action.

cleanshot_capture_previous_areaB

Repeat the last taken screenshot

Inputs: action.

cleanshot_capture_textB

Open CleanShot's Text Recognition (OCR) tool or extract text from a file

Inputs: x, y, width, height, +3 more.

cleanshot_capture_windowB

Open CleanShot's Capture Window mode

Inputs: action.

cleanshot_hide_desktop_iconsB

Hide desktop icons

Inputs: no named parameters.

cleanshot_open_annotateB

Open a file in CleanShot's Annotate tool

Inputs: filepath.

cleanshot_open_from_clipboardA

Open the image from clipboard in CleanShot's Annotate tool

Inputs: no named parameters.

cleanshot_open_historyB

Open CleanShot's capture history

Inputs: no named parameters.

cleanshot_open_settingsA

Open CleanShot settings with optional tab

Inputs: tab.

cleanshot_pinC

Open a file as a pinned screenshot

Inputs: filepath.

cleanshot_record_screenC

Open CleanShot's Record Screen mode

Inputs: x, y, width, height, +1 more.

cleanshot_restore_recently_closedB

Restore the most recently closed file from history

Inputs: no named parameters.

cleanshot_scrolling_captureC

Open CleanShot's Scrolling Capture mode

Inputs: x, y, start, width, +3 more.

cleanshot_self_timerB

Open CleanShot's Capture Area mode with self-timer

Inputs: action.

cleanshot_show_desktop_iconsB

Show desktop icons

Inputs: no named parameters.

cleanshot_toggle_desktop_iconsA

Toggle desktop icons visibility

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools target distinct actions such as capture modes, history, settings, and annotations. Some overlap exists between capture_area, self_timer, and all_in_one, but descriptions clarify the differences, and toggle vs show/hide is a minor overlap.

    Naming Consistency4/5

    All tools share the cleanshot_ prefix and mostly follow a verb_noun structure (capture_fullscreen, open_history). A few exceptions like all_in_one and self_timer are mode names, but overall the pattern is predictable.

    Tool Count4/5

    19 tools is on the higher end but appropriate for a feature-rich screenshot utility, each mapping to a distinct feature. Some consolidation of desktop icon tools could reduce count, but it is not excessive.

    Completeness4/5

    The tool set covers the main CleanShot capabilities: various capture modes, OCR, annotation, history, settings, and desktop icon management. Minor gaps like direct file saving or sharing exist, but the core workflows are covered.

    Related MCP Connectors

    Related MCP Servers