capture-win-mcp

MCP (Model Context Protocol) server for capturing macOS windows and tracking Spaces. This server provides tools for AI assistants to interact with macOS windows through yabai and the built-in screencapture utility.

📖 | 📦 | 👨‍💻

Features

List Windows: Get detailed information about all windows organized by macOS Space (virtual desktop)
Capture Window: Take screenshots of specific windows by their ID

Prerequisites

macOS (tested on macOS 15+)
Python 3.12 or higher
yabai window manager

Installing yabai

brew install koekeishiya/formulae/yabai yabai --start-service

Installation

Method 1: Install from GitHub (Recommended)

Using uv:

uv pip install git+https://github.com/huegli/capture-win-mcp.git

Using pip:

pip install git+https://github.com/huegli/capture-win-mcp.git

Method 2: Install from PyPI

Once published to PyPI:

# Using uv uv pip install capture-win-mcp # Using pip pip install capture-win-mcp

Method 3: Install from Source (For Development)

# Clone the repository git clone https://github.com/huegli/capture-win-mcp.git cd capture-win-mcp # Create virtual environment uv venv # or: python3 -m venv venv source .venv/bin/activate # Install in editable mode uv pip install -e . # or: pip install -e .

Usage

As an MCP Server

Claude Desktop Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

If installed via pip/uv (recommended):

{ "mcpServers": { "capture-win": { "command": "capture-win-mcp" } } }

If running from source directory:

{ "mcpServers": { "capture-win": { "command": "uv", "args": [ "--directory", "/absolute/path/to/capture-win-mcp", "run", "capture-win-mcp" ] } } }

If using a specific Python environment:

{ "mcpServers": { "capture-win": { "command": "/path/to/venv/bin/capture-win-mcp" } } }

After adding the configuration, restart Claude Desktop for the changes to take effect.

Available Tools

`list_windows`

Lists all windows organized by macOS Space.

Parameters:

format (optional): Output format - "json" (default) or "summary"

Example:

{ "format": "summary" }

Returns: Window and Space information including:

Space index, label, visibility status
Window ID, title, app name, position, size
Window counts per Space

`capture_window`

Captures a screenshot of a specific window.

Parameters:

window_id (required): The window ID to capture (get this from list_windows)
include_shadow (optional): Include window shadow in capture (default: true)

Example:

{ "window_id": 12345, "include_shadow": false }

Returns: Base64-encoded PNG image of the window

Standalone Usage

You can also use the original window tracking functionality:

# Show windows by space python main.py # Show spaces summary python main.py --spaces # Export to JSON python main.py --export output.json

Development

# Create virtual environment python3 -m venv venv source venv/bin/activate # Install in development mode pip install -e . # Run the MCP server python -m capture_win_mcp.server

Architecture

capture_win_mcp/tracker.py: EnhancedSpaceTracker class that interfaces with yabai
capture_win_mcp/server.py: MCP server implementation with tools
main.py: Standalone CLI tool for window tracking

Troubleshooting

"yabai not found" error

Make sure yabai is installed and running:

brew install koekeishiya/formulae/yabai yabai --start-service

Window capture fails

Ensure the window ID is valid (use list_windows first)
Check that macOS Screen Recording permissions are granted
Some system windows may not be capturable

License

MIT

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

GitHub Repository

Need Help?

Report Issue

Related Servers

Capture Win MCP