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:

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

⭐ Star this repo if you find it useful!

Created with Amp by Sourcegraph