Macos Screen MCP

🚀 macOS Screen View and Control MCP Server

A Model Context Protocol (MCP) server that provides window screenshot functionality. This server enables Large Language Models (LLMs) to capture screenshots of specific windows on macOS, which can be located by window title or window ID.

🚀 Quick Start

The macOS Screen View and Control MCP Server allows LLMs to interact with the macOS screen, providing functions such as taking window screenshots, listing windows, and simulating keyboard input.

✨ Features

Provided Tools

• capture_window_screenshot - Capture a screenshot of a specified window, which can be identified by its title or ID.

  • window_identifier (string, required): The title or ID of the window to find.
  • search_in_owner (boolean, optional): Whether to search in the window owner's name (default: true).
  • format (string, optional): The output format (binary or base64) (default: "binary").

• list_windows - List all visible windows.

  • No parameters required.

• find_window - Find a window by title or owner name.

  • title (string, required): The title or owner name of the window to find.
  • search_in_owner (boolean, optional): Whether to search in the window owner's name (default: true).

• send_key - Send a keyboard key event to the active window.

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

• type_text - Type a string of text characters.

  • text (string, required): The text to type.
  • delay (float, optional): The 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 includes right_shift, right_option, right_control).

💻 Usage Examples

Basic Usage

Send a single key

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://git@github.com/jhead/macos-screen-mcp.git

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

python -m macos_screen_mcp

📚 Documentation

Configuration

Set up the configuration

Add the following to your Claude or Cursor settings:

"mcpServers": {
 "macos-screen": {
    "name": "macos-screen",
    "url": "http://localhost:8000/sse",
    "description": "MCP server for capturing window screenshots",
    "version": "1.0.0"
  }
}

Debugging

You can use the MCP inspector to debug the server:

npx @modelcontextprotocol/inspector python -m macos_screen_mcp

🤝 Contribution

We welcome any contributions to help expand and improve macos-screen-mcp. Whether you're adding new features, enhancing existing ones, or improving the documentation, your input is valuable.

Feel free to submit pull requests! Please share your new ideas, bug fixes, or improvements to make macos-screen-mcp more powerful and useful.

📄 License

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