What is Macos Screen Mcp

macos-screen-mcp is a Model Context Protocol server designed to capture screenshots and control macOS windows. It allows large language models (LLMs) to take screenshots of specific windows based on their title or ID.

Use cases

Use cases include automated testing of applications by capturing window states, creating tutorials by taking screenshots, automating repetitive tasks by sending key events, and developing applications that require window management.

How to use

To use macos-screen-mcp, install it via pip and utilize its available tools such as ‘capture_window_screenshot’ to capture screenshots, ‘list_windows’ to list visible windows, ‘find_window’ to locate a window, ‘send_key’ to simulate key presses, and ‘type_text’ to input text.

Key features

Key features include the ability to capture screenshots of specific windows, list all visible windows, find windows by title or owner name, send key press events to the active window, and type text with customizable delays.

Where to use

macos-screen-mcp can be used in various fields such as software testing, automation tasks, user interface development, and any application requiring interaction with macOS windows.

macOS Screen View & Control MCP Server

A Model Context Protocol server that provides window screenshot capabilities. This server enables LLMs to capture screenshots of specific windows on macOS, either by window title or window ID.

Available Tools

• capture_window_screenshot - Captures a screenshot of a specific window by its title or ID

  • window_identifier (string, required): Window title to search for or window ID
  • search_in_owner (boolean, optional): Whether to search in window owner names (default: true)
  • format (string, optional): Output format (binary or base64) (default: “binary”)

• list_windows - Lists all visible windows

  • No parameters required

• find_window - Finds a window by title or owner name

  • title (string, required): Window title or owner name to search for
  • search_in_owner (boolean, optional): Whether to search in window owner names (default: true)

• send_key - Sends a keyboard key press event to the active window

  • key (string, required): The key to press (e.g., ‘a’, ‘return’, ‘space’)
  • modifiers (list of strings, optional): List of modifier keys to hold (e.g., [‘command’, ‘shift’])

• type_text - Types a sequence of text characters

  • text (string, required): The text to type
  • delay (float, optional): Delay between keystrokes in seconds (default: 0.1)

Supported Keys

The following keys are supported:

• Letters: a-z (case-insensitive)
• Numbers: 0-9
• Special keys: return, tab, space, delete, escape
• Arrow keys: up_arrow, down_arrow, left_arrow, right_arrow
• Modifier keys: command, shift, control, option (also right_shift, right_option, right_control)

Examples

Send a single key press:

await send_key("return")

Send a key with modifiers:

await send_key("c", ["command"])  # Command+C (copy)

Type text:

await type_text("Hello, World!")

Installation

Using pip

Install macos_screen_mcp via pip:

pip install git+ssh://[email protected]/jhead/macos-screen-mcp.git

After installation, you can run it as a script using:

python -m macos_screen_mcp

Configuration

Configure

Add to your Claude or Cursor settings:

Debugging

You can use the MCP inspector to debug the server:

npx @modelcontextprotocol/inspector python -m macos_screen_mcp

Contributing

We encourage contributions to help expand and improve macos-screen-mcp. Whether you want to add new tools, enhance existing functionality, or improve documentation, your input is valuable.

Pull requests are welcome! Feel free to contribute new ideas, bug fixes, or enhancements to make macos-screen-mcp even more powerful and useful.

License

macos-screen-mcp is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.