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.
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
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
macOS (tested on macOS 15+)
Python 3.12 or higher
yabai window manager
brew install koekeishiya/formulae/yabai
yabai --start-serviceUsing uv:
uv pip install git+https://github.com/huegli/capture-win-mcp.gitUsing pip:
pip install git+https://github.com/huegli/capture-win-mcp.gitOnce published to PyPI:
# Using uv
uv pip install capture-win-mcp
# Using pip
pip install capture-win-mcp# 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 .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.
list_windowsLists 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_windowCaptures 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
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# 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.servercapture_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
Make sure yabai is installed and running:
brew install koekeishiya/formulae/yabai
yabai --start-serviceEnsure the window ID is valid (use list_windows first)
Check that macOS Screen Recording permissions are granted
Some system windows may not be capturable
MIT
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.
| Name | Required | Description | Default |
|---|---|---|---|
| window_id | Yes | The window ID to capture (from list_windows) | |
| include_shadow | No | Include window shadow in the capture |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It describes the return format ('Returns the image as base64-encoded PNG') which is valuable, but doesn't mention potential limitations like window visibility requirements, performance impact, or error conditions. It provides basic behavioral context but could be more comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise with two sentences that each serve distinct purposes: the first states the tool's purpose and return format, the second provides usage guidance. There's no wasted language and it's front-loaded with the core functionality.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (screenshot capture with parameters), no annotations, and no output schema, the description does well by explaining the return format and workflow. However, it could provide more context about potential constraints or error cases. It's mostly complete but has minor gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents both parameters. The description mentions window IDs come from 'list_windows' which adds some context, but doesn't provide additional semantic meaning beyond what's in the schema descriptions. This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Capture a screenshot') and target resource ('a specific window by its ID'), distinguishing it from the sibling tool 'list_windows' which provides window IDs. It uses precise verbs and resources without being vague or tautological.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool ('Capture a screenshot of a specific window by its ID') and provides a clear alternative/pre-requisite ('Use list_windows first to get window IDs'). This gives complete guidance on tool selection and workflow.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all windows organized by macOS Space. Returns detailed information about windows, spaces, and which windows belong to which Space.
| Name | Required | Description | Default |
|---|---|---|---|
| format | No | Output format: 'json' (structured data) or 'summary' (human-readable) | json |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions the tool returns 'detailed information about windows, spaces, and which windows belong to which Space,' which gives some behavioral insight. However, it lacks critical details like whether this requires permissions, how data is sourced (real-time vs cached), performance characteristics, or error handling. For a tool with no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero waste: the first states the purpose and scope, and the second specifies the return content. It's front-loaded with the core functionality and appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 optional parameter, no output schema, no annotations), the description is minimally complete. It covers what the tool does and what it returns, but lacks behavioral details that would be helpful for an agent (e.g., permissions, data freshness). Without annotations or output schema, it's adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents the single parameter 'format' with its enum values and default. The description adds no parameter-specific information beyond what the schema provides, which is acceptable given the high coverage. Baseline 3 is appropriate as the schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('windows organized by macOS Space'), specifies the scope ('all windows'), and distinguishes from the sibling tool 'capture_window' by focusing on listing rather than capturing. It's specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions the sibling tool 'capture_window' exists but gives no context on when to choose listing over capturing or other potential scenarios. Usage is implied but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
capture_windowlist_windowsScored 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.
Let ChatGPT, Claude & Cursor use your Mac: email, calendar, iMessage, Teams, files. Local, free.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
MCP connector that lets ChatGPT list, search, and run your Apple Shortcuts via a local Mac agent
PDF, image, video, OCR, screenshot, SQL, QR and text tools for agents. No API key, no signup.
