mouseless

Rust MCP server for macOS desktop control — screenshots, mouse, keyboard, apps. Over stdio or Streamable HTTP.

Quick start

curl -fsSL https://raw.githubusercontent.com/smithery-ai/mouseless/master/scripts/install.sh | bash

Point any MCP client at it — mouseless runs stdio by default:

{ "mcpServers": { "mouseless": { "command": "mouseless" } } }

Set INSTALL_DIR or VERSION to override the install script's defaults (~/.local/bin, latest).

Other install options

Smithery:

smithery mcp add smithery/mouseless

From crates.io:

cargo install mouseless

Claude Desktop bundle — download mouseless-vX.Y.Z.mcpb from the latest release and drop it in.

Usage

mouseless                       # stdio (default)
mouseless --http [ADDR]         # HTTP (default 127.0.0.1:3100)
mouseless --help | --version

HTTP client config: { "url": "http://127.0.0.1:3100/mcp" }. RUST_LOG tunes verbosity (default info).

Requirements

macOS (aarch64 / x86_64). Grant Accessibility and Screen Recording in System Settings > Privacy & Security.

Tools (21)

Tool	Description
screenshot	Capture the primary display (MCP ImageContent)
zoom	High-res capture of a screen region
left_click / right_click / middle_click	Click with optional modifiers
double_click / triple_click	Multi-click at coordinates
left_click_drag	Click-drag with animated move
scroll	Scroll up/down/left/right at coordinates
mouse_move	Move cursor without clicking
left_mouse_down / left_mouse_up	Press/release left button
cursor_position	Get current cursor coordinates
key / hold_key	Key combo (xdotool syntax) or hold for N seconds
type	Type text into focused element
read_clipboard / write_clipboard	pbpaste / pbcopy (write verifies)
open_application	Launch or focus an app by name or bundle ID
wait	Sleep for N seconds
computer_batch	Execute a sequence of actions in one call

Build from source

git clone https://github.com/smithery-ai/mouseless && cd mouseless
cargo build --release

Release (maintainers)

Tag and push — CI builds both darwin targets, attaches tarballs + .mcpb to the GitHub Release, and runs cargo publish:

git tag v0.1.2 && git push origin v0.1.2

Architecture

src/
├── main.rs              # arg parsing, startup banner, transport dispatch
├── server.rs            # MCP tool handlers, HTTP transport
├── display/ capture/    # display geometry, Retina scaling, xcap screenshots, zoom
├── input/               # dedicated enigo thread, mouse/keyboard/drag/scroll/animation
├── clipboard.rs apps.rs batch.rs   # pbcopy/pbpaste, app launch, batch dispatch
├── types.rs             # ScreenCoord / LogicalCoord / PhysicalCoord
└── error.rs             # 3-tier error hierarchy

Coordinates from the model are in the resized screenshot space (max 1280×768) and converted to macOS logical points — three distinct Rust types prevent mixing spaces at compile time. Enigo runs on a dedicated OS thread with mpsc/oneshot channels to avoid CGEventSource thread-affinity issues.

License

MIT