Capture Win MCP
Provides tools for capturing screenshots of macOS windows and listing window information organized by Spaces (virtual desktops), enabling interaction with the macOS window system.
Interfaces with the yabai window manager to retrieve detailed window and Space information on macOS, including window positions, sizes, titles, and Space organization.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Capture Win MCP list all windows organized by space"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-serviceInstallation
Method 1: Install from GitHub (Recommended)
Using uv:
uv pip install git+https://github.com/huegli/capture-win-mcp.gitUsing pip:
pip install git+https://github.com/huegli/capture-win-mcp.gitMethod 2: Install from PyPI
Once published to PyPI:
# Using uv
uv pip install capture-win-mcp
# Using pip
pip install capture-win-mcpMethod 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 fromlist_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.jsonDevelopment
# 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.serverArchitecture
capture_win_mcp/tracker.py: EnhancedSpaceTracker class that interfaces with yabaicapture_win_mcp/server.py: MCP server implementation with toolsmain.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-serviceWindow capture fails
Ensure the window ID is valid (use
list_windowsfirst)Check that macOS Screen Recording permissions are granted
Some system windows may not be capturable
License
MIT
Available Tools
2 toolscapture_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
Scored across 2 tools
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.
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.
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.
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
Related MCP Connectors
- DNS-DATA RemoteDeprecatedcom.dns-data
Connect AI assistants to authorized Windows and macOS devices for files, commands, and management.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Mac & Windows: let ChatGPT, Claude & Cursor use your email, calendar, iMessage, Teams, files.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables 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.35 npm2MIT
- AlicenseBqualityCmaintenanceEnables 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.441MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to automate macOS desktop tasks including mouse control, keyboard input, screenshots, window management, and UI interaction.417MIT
- AlicenseAqualityDmaintenanceEnables AI agents to control macOS desktop apps via screenshots, mouse clicks, keyboard input, accessibility queries, and AppleScript.118 npmMIT