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.

📖 Quick Start Guide | 📦 Distribution Guide | 👨‍💻 Developer Docs

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