# Cleanshot Mcp

> An MCP server for CleanShot X (macOS)

- **Type:** MCP server
- **Install:** `agentstack add mcp-jdorfman-cleanshot-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jdorfman](https://agentstack.voostack.com/s/jdorfman)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jdorfman](https://github.com/jdorfman)
- **Source:** https://github.com/jdorfman/cleanshot-mcp

## Install

```sh
agentstack add mcp-jdorfman-cleanshot-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)](https://modelcontextprotocol.io) - a standard for connecting AI assistants to external tools. Works with [Amp](https://ampcode.com), Claude Desktop, and other MCP-compatible applications._

## Requirements

- macOS
- [CleanShot X](https://cleanshot.com/) installed and running
  - ⚙️ Settings > Advanced > API > ☑️ Allow applications to control CleanShot X
- Node.js 18+

## Quick Start

### 1. Install the MCP Server

```bash
# 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:

```json
{
  "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

```bash
npm run build
```

### Development Mode

```bash
npm run dev
```

### Testing

Make sure CleanShot is installed and running, then test individual commands:

```bash
# 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](https://github.com/jdorfman/cleanshot-mcp/issues)
- **MCP protocol questions**: [MCP Documentation](https://modelcontextprotocol.io)

> [!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](https://github.com/jdorfman/cleanshot-mcp)** if you find it useful!

_Created with [Amp](https://ampcode.com/threads/T-6a3d9fd7-62e8-4e14-b6e8-f1b8ad9c4348) 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](https://github.com/jdorfman)
- **Source:** [jdorfman/cleanshot-mcp](https://github.com/jdorfman/cleanshot-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jdorfman-cleanshot-mcp
- Seller: https://agentstack.voostack.com/s/jdorfman
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.