https://github.com/jhead/macos-screen-mcp
MCP Server to screenshot and control macOS windows (made for Cursor)
https://github.com/jhead/macos-screen-mcp
Last synced: 2 months ago
JSON representation
MCP Server to screenshot and control macOS windows (made for Cursor)
- Host: GitHub
- URL: https://github.com/jhead/macos-screen-mcp
- Owner: jhead
- License: mit
- Created: 2025-04-06T06:34:29.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-05-07T02:18:16.000Z (6 months ago)
- Last Synced: 2025-05-07T03:26:41.258Z (6 months ago)
- Language: Python
- Size: 12.7 KB
- Stars: 3
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-mcp-servers - **macos-screen-mcp** - MCP Server to screenshot and control macOS windows (made for Cursor) `python` `mcp` `server` `pip install git+https://github.com/jhead/macos-screen-mcp` (🤖 AI/ML)
- awesome-mcp-servers - **macos-screen-mcp** - MCP Server to screenshot and control macOS windows (made for Cursor) `python` `mcp` `server` `pip install git+https://github.com/jhead/macos-screen-mcp` (🤖 AI/ML)
README
# 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:
```python
await send_key("return")
```
Send a key with modifiers:
```python
await send_key("c", ["command"]) # Command+C (copy)
```
Type text:
```python
await type_text("Hello, World!")
```
## Installation
### Using pip
Install `macos_screen_mcp` via pip:
```bash
pip install git+ssh://git@github.com/jhead/macos-screen-mcp.git
```
After installation, you can run it as a script using:
```bash
python -m macos_screen_mcp
```
## Configuration
### Configure
Add to your Claude or Cursor settings:
```json
"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:
```bash
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.