# 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](QUICK_START.md)** | **📦 [Distribution Guide](DISTRIBUTION.md)** | **👨‍💻 [Developer Docs](CLAUDE.md)**

## 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](https://github.com/koekeishiya/yabai) window manager

### Installing yabai

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

## Installation

### Method 1: Install from GitHub (Recommended)

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

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

### Method 2: Install from PyPI

Once published to PyPI:
```bash
# Using uv
uv pip install capture-win-mcp

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

### Method 3: Install from Source (For Development)

```bash
# 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):**
```json
{
  "mcpServers": {
    "capture-win": {
      "command": "capture-win-mcp"
    }
  }
}
```

**If running from source directory:**
```json
{
  "mcpServers": {
    "capture-win": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/capture-win-mcp",
        "run",
        "capture-win-mcp"
      ]
    }
  }
}
```

**If using a specific Python environment:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:

```bash
# Show windows by space
python main.py

# Show spaces summary
python main.py --spaces

# Export to JSON
python main.py --export output.json
```

## Development

```bash
# 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:

```bash
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