cleanshot-mcp

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.

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:

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

• Issues with this MCP server: Open a GitHub issue
• MCP protocol questions: MCP Documentation

[!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