cleanshot-mcp

jdorfman/cleanshot-mcp

3.3

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

The CleanShot MCP Server is an unofficial Model Context Protocol server that integrates with CleanShot's URL scheme API, allowing programmatic control of CleanShot actions through MCP-compatible applications.

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+

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:

CommandWhat 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

|

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] Please DO 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