Skip to main content
Glama

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

Related MCP server: mac-mcp-server

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

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

Available Tools

2 tools
capture_windowA

Capture a screenshot of a specific window by its ID. Returns the image as base64-encoded PNG. Use list_windows first to get window IDs.

Inputs: window_id (required), include_shadow.

list_windowsB

List all windows organized by macOS Space. Returns detailed information about windows, spaces, and which windows belong to which Space.

Inputs: format.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have completely distinct purposes: list_windows enumerates available windows with organizational details, while capture_window takes a specific window ID to capture an image. There is no overlap in functionality, and the descriptions clearly differentiate their roles, making misselection unlikely.

    Naming Consistency5/5

    Both tools follow a consistent verb_noun naming pattern (list_windows, capture_window), using snake_case throughout. The naming is predictable and aligns well with their actions, providing clear and uniform identification.

    Tool Count4/5

    With only 2 tools, the server is minimal but appropriately scoped for its purpose of window listing and screenshot capture. It feels slightly thin, as additional related operations (e.g., capturing the entire screen or managing windows) could enhance coverage, but the core workflow is supported without bloat.

    Completeness4/5

    For the domain of window management and screenshot capture, the tools cover the essential workflow: listing windows to obtain IDs and capturing specific windows. A minor gap exists, such as the inability to capture the entire screen or multiple windows at once, but agents can effectively use the provided tools without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to capture and analyze screenshots of macOS applications, windows, or the entire screen using local (Ollama) or cloud-based AI vision models, with non-intrusive, fast screen capture via Apple's ScreenCaptureKit.
      3
      5 npm
      2
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to automate macOS through AppleScript and JXA by providing 44 tools for application management, window control, and UI interaction. It allows for comprehensive system control including screen capture, keyboard and mouse simulation, and system information retrieval.
      44
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to automate macOS desktop tasks including mouse control, keyboard input, screenshots, window management, and UI interaction.
      417
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to control macOS desktop apps via screenshots, mouse clicks, keyboard input, accessibility queries, and AppleScript.
      11
      8 npm
      MIT