cleanshot-cli

Kommandozeile für CleanShot X auf macOS, in Python. Neuschreibung des Go-Werkzeugs XiaofengXie16/cleanshot-cli.

Jeder Befehl wird in eine cleanshot://-URL übersetzt und per open an die App übergeben. CleanShot X muss installiert sein. Das URL-Schema meldet nicht zurück, ob die Aktion geklappt hat. Die Ausgabe sagt deshalb nur „übergeben“.

Installation

uv tool install .          # stellt den Befehl `cleanshot-cli` bereit
# oder im Projekt:
uv sync && uv run cleanshot-cli --help

Related MCP server: Screenshot MCP (macOS)

Befehle

Optionen:

• -a, --action: copy, save, annotate, upload, pin

• -d, --display: Bildschirm, ab 1

• --x --y --width --height: nur alle vier zusammen; 0 ist eine gültige Koordinate

• -f, --file: Bilddatei, muss existieren, wird zum absoluten Pfad

Globale Optionen (vor dem Befehl): -v/--verbose gibt die URL aus, -q/--quiet unterdrückt die Ausgabe, -n/--dry-run gibt nur die URL aus und ruft nichts auf, --version.

cleanshot-cli capture-fullscreen -a copy
cleanshot-cli capture-area --x 0 --y 0 --width 800 --height 600 -a upload
cleanshot-cli -n capture-text -f "$HOME/Desktop/Bild mit Leerzeichen.png"
cleanshot-cli settings -t shortcuts

MCP-Server

cleanshot-cli mcp startet einen MCP-Server über stdio. Dafür braucht es das optionale Extra mcp:

uv tool install '.[mcp]'
claude mcp add cleanshot -- cleanshot-cli mcp

Ohne Installation, direkt aus dem Projekt:

claude mcp add cleanshot -- uv --directory ~/src_own/cleanshot-cli run --extra mcp cleanshot-cli mcp

Für Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "cleanshot": { "command": "cleanshot-cli", "args": ["mcp"] }
  }
}

Nur capture_image und latest_capture liefern ein Bild. Alle anderen Werkzeuge melden nur, dass der Befehl übergeben wurde. Bei area, window und scrolling muss ein Mensch am Bildschirm auswählen.

Den Speicherordner liest der Server aus den CleanShot-Einstellungen (defaults read pl.maketheweb.cleanshotx exportPath). Mit CLEANSHOT_EXPORT_DIR lässt er sich überschreiben, Rückfall ist ~/Desktop. Bilder mit einer Kante über 1568 px werden vor der Rückgabe per sips verkleinert.

Unterschiede zur Go-Vorlage

• x=0 / y=0 gehen nicht mehr verloren.

• Leerzeichen werden als %20 statt + kodiert.

• Ungültige Werte für --action/--display, unvollständige Bereiche und fehlende Dateien werden abgelehnt, bevor CleanShot aufgerufen wird.

• Erfolgsmeldungen versprechen nichts, was das URL-Schema nicht bestätigt.

• --version, --dry-run, --verbose, --quiet und Tests sind neu.

• pin nimmt zusätzlich --file.

Entwicklung

uv sync --extra mcp
uv run pytest
uv run ruff check . && uv run ruff format --check .
uv run mypy

Die Tests ersetzen subprocess.run per autouse-Fixture und rufen CleanShot nie wirklich auf.

Lizenz

MIT, siehe LICENSE. CleanShot X ist ein kommerzielles Produkt von MakeTheWeb; dieses Projekt steht in keiner Verbindung dazu.