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](TOOLS.md) | [📕 API Reference](API.md)

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_

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jdorfman
• Source: jdorfman/cleanshot-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.