openowl

An MCP server that gives any AI assistant eyes and hands on your desktop — screenshots, clicking, typing, OCR, window management, accessibility-tree queries, workflow recording.

Apache-2.0 licensed. No account, no API key, no usage limits, no telemetry. 40+ tools.

Prefer a hosted version? A managed cloud build with a signed binary, one-click setup, and email support is available at openowl.dev. Same code, no setup.

Install

From source (recommended)

git clone https://github.com/mihir-kanzariya/openowl
cd openowl
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[macos]"      # or [windows]
openowl --version

pip install -e . adds the openowl console script to the venv. Anywhere that venv is on PATH, the command is callable.

From PyPI (coming soon)

pip install "openowl[macos]"   # or [windows]
# or zero-install via uvx:
uvx openowl

PyPI publish is queued for the first tagged release. Until then, install from source above.

Configure your MCP client

The server speaks stdio. Point any MCP client at the openowl command — the path it lives at depends on your install method.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "owl": {
      "command": "/absolute/path/to/openowl/.venv/bin/openowl"
    }
  }
}

Replace the path with the output of which openowl after activating your venv. (Once PyPI publish lands you'll be able to use "command": "uvx", "args": ["openowl"] instead.)

Claude Code

claude mcp add owl --transport stdio -s user -- /absolute/path/to/openowl/.venv/bin/openowl

Codex / Cline / any MCP client

Run the openowl binary over stdio. Same configuration shape — point your client at the absolute path.

Permissions (macOS)

On first run, macOS will prompt to grant Accessibility and Screen Recording permissions. The server checks both at startup and prints which are missing. Open System Settings → Privacy & Security → grant access → restart your MCP client.

Permissions are remembered per-binary path. Reinstalling into the same venv keeps them; switching to uvx (which uses an ephemeral path) re-prompts every run, so for daily use prefer the venv install above.

Tools (40)

Category	Tools
Screen capture	screenshot, screenshot_baseline, screenshot_diff, manage_screenshots, get_screen_size
Input	click, type_text, paste_text, send_keys, scroll, drag, hover, get_mouse_position
Click via search	click_text, click_in_region, click_element, find_text, find_element, smart_find
Windows	list_windows, focus_window, launch_app, set_target_window, get_target_window, virtual_desktop
UI Automation	list_elements, get_focused_element, ui_fingerprint, detect_framework
Watching	wait_for_change, start_watcher, stop_watcher, get_notifications
Workflow recording	record_workflow, replay_workflow_tool, list_workflows_tool, delete_workflow_tool
System	clipboard, batch_actions, configure_uac

Run openowl --version to print the version.

Pre-built workflows

Looking for ready-made automation recipes? See mihir-kanzariya/openowl-templates — a separate repo of pre-built workflows for openowl + Claude Code. Clone, configure, run.

Platforms

• macOS — full support (Accessibility + Screen Recording + Vision OCR APIs via PyObjC).
• Windows — full support via pywinauto + Win32 + RapidOCR.
• Linux — not supported.

Development

git clone https://github.com/mihir-kanzariya/openowl
cd openowl
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,macos]"   # or [dev,windows]
pytest                          # 20 tests
ruff check .

See CONTRIBUTING.md for the full workflow.

License

Apache License 2.0. See LICENSE and NOTICE for details, including attribution for inherited code.

---

Maintained by Mihir Kanzariya. For a hosted, managed version with a signed binary and email support, see openowl.dev.