screenmcp-claude-plugin

A Claude Code plugin that gives Claude local desktop vision and control — screenshot, click, drag, type, hotkeys, window management, and clipboard — for the machine it's running on. Windows, macOS, Linux.

It bundles the standalone single-file ScreenMCP stdio MCP server (screenmcp_cli.py). No worker, relay, account, or network — it talks to the desktop directly over stdio.

Install

This repo doubles as its own Claude Code marketplace. In Claude Code:

/plugin marketplace add shimondoodkin/screenmcp-claude-plugin
/plugin install screenmcp-claude-plugin@screenmcp-claude-plugin

Once installed, the screenmcp-local MCP server registers automatically.

Self-installing dependencies

The plugin's .mcp.json launches bootstrap.py, which on first run ensures the Python runtime dependencies are importable and installs any that are missing (preferring uv pip, falling back to python -m pip):

mss  pynput  Pillow  pyperclip  pygetwindow   # (pygetwindow: Windows only)

So there is normally nothing to install by hand. You just need Python 3.9+ on PATH. Optional extras (install only if needed):

pip install opencv-python   # camera / list_cameras
pip install simpleaudio     # play_audio

What Claude can do

After install, Claude has tools like screenshot, click, double_click, drag, scroll, type, hotkey, list_windows, focus_window, copy/paste, and more. The bundled skill (skills/screenmcp) teaches Claude when and how to use them — including the 1456×819 coordinate space and the model sizing argument.

Coordinates

Screenshots default to 1456×819; click/drag/scroll coordinates are in that space and auto-scale to your real screen. Pass model: "claude" to size the screenshot and click space to Claude's vision limits. Override with max_width/max_height (0 = native pixels).

Layout

.claude-plugin/plugin.json   plugin manifest
.claude-plugin/marketplace.json  makes this repo installable as a marketplace
.mcp.json                    registers the screenmcp-local server
bootstrap.py                 self-installing launcher → screenmcp_cli.run()
screenmcp_cli.py             vendored single-file stdio MCP server
pyproject.toml               dependency declarations
skills/screenmcp/SKILL.md    how/when Claude should drive the desktop
tests/                       unit + end-to-end stdio tests

Platform notes

• macOS: grant Screen Recording and Accessibility to the launching app on first use, then restart it.
• Linux: sudo apt install wmctrl xdotool for window operations. Wayland is best-effort.
• ui_tree and elevate are not implemented in this local stdio server.

Credits

Vendored from the python-cli of the ScreenMCP project. See python-cli-README.md for the upstream server docs.

License

MIT — see LICENSE.