cleanshot-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cleanshot-mcp Take a fullscreen screenshot and copy it"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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+
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-mcp2. 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 buildDevelopment Mode
npm run devTesting
Make sure CleanShot is installed and running, then test individual commands:
# Test basic functionality
node dist/index.jsContributing
Fork the repository
Create a feature branch
Make your changes
Submit a pull request
Support
Issues with this MCP server: Open a GitHub issue
MCP protocol questions: MCP Documentation
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 toolscleanshot_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
Scored across 19 tools
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.
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.
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.
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
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Give Claude, Cursor, or another AI assistant direct access to your QuickSnip library.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude to see and interact with any macOS application using natural language commands. Perfect for testing Mac applications, UI automation, and app development with AI assistance.16 PyPI34MIT
- AlicenseDqualityDmaintenanceEnables AI assistants to capture and analyze screenshots using Claude Vision API, providing AI-powered insights about desktop interface content, UI elements, and visual layouts.259 npm2MIT
- AlicenseAqualityDmaintenanceEnables AI agents to capture and analyze screenshots of macOS applications, windows, or the entire screen using local (Ollama) or cloud-based AI vision models, with non-intrusive, fast screen capture via Apple's ScreenCaptureKit.323 npm2MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to automate macOS desktop tasks including mouse control, keyboard input, screenshots, window management, and UI interaction.10 npm415MIT