list_windows

List all visible windows with their IDs, titles, and application names.

Overview

The list_windows tool provides information about all visible windows on macOS. This is essential for targeted window capture using the take_screenshot tool with specific window IDs.

Purpose

• Window Discovery: Find specific application windows
• Targeted Capture: Get window IDs for screenshot capture
• Window Management: See all open windows and their properties
• Debugging: Identify window hierarchy and properties

Input Schema

{
  "type": "object",
  "properties": {}
}

No parameters required.

Output

Returns a list of all visible windows:

{
  "content": [
    {
      "type": "text",
      "text": "Found 15 windows:\n\nID: 1 | App: Google Chrome | Title: GitHub - orchestre/mcp | Position: 0,25 | Size: 1920x1055\nID: 2 | App: Visual Studio Code | Title: orchestre - server.ts | Position: 960,25 | Size: 960x1055\n..."
    }
  ]
}

Window Information

Each window includes:

Field	Description	Example
id	Window ID for capture	1
app	Application name	Google Chrome
title	Window title	GitHub - orchestre/mcp
position	X,Y coordinates	0,25
size	Width x Height	1920x1055

Platform Support

Platform	Supported
macOS	✅
Linux	❌
Windows	❌

Examples

Basic Window Listing

const windows = await list_windows({});
// Returns formatted list of all windows

Find and Capture Specific App

// List all windows
const result = await list_windows({});

// Parse the result to find Chrome
// Window IDs can be extracted from the formatted output

// Capture Chrome window (example ID)
await take_screenshot({ windowId: 1 });

Workflow Example

// 1. List windows to see what's available
const windows = await list_windows({});

// 2. User identifies window of interest from list
// "ID: 5 | App: Slack | Title: orchestre-dev"

// 3. Capture that specific window
await take_screenshot({ windowId: 5 });

Permissions

macOS Requirements

• Screen Recording Permission: May be required
• Grant in: System Preferences → Security & Privacy → Privacy → Screen Recording

Window Filtering

The tool automatically filters out:

• System windows (WindowServer, Dock, etc.)
• Windows without titles
• Windows smaller than 50x50 pixels
• Desktop elements

Use Cases

1. Application-Specific Screenshots

// Find all VS Code windows
const windows = await list_windows({});
// Look for windows where App contains "Code"
// Capture specific VS Code window

2. Multi-Monitor Setup

// List windows shows position
const windows = await list_windows({});
// Position helps identify which monitor
// Capture window on specific monitor

3. Documentation

// Document all open applications
const windows = await list_windows({});
// Creates a snapshot of workspace state

Technical Details

Window ID vs Core Graphics ID

• id: Sequential ID for easy reference (1, 2, 3...)
• cgWindowID: Internal Core Graphics ID used for capture
• The tool handles the mapping automatically

Window Geometry

• Position: Top-left corner coordinates
• Size: Width and height in pixels
• Coordinates are screen-relative

Best Practices

1. Always List First: Before capturing specific windows
2. Check Platform: Only works on macOS
3. Handle Permissions: May need screen recording permission
4. Verify Window Exists: Windows can close between list and capture

Error Handling

Error	Cause	Solution
"Window listing is only supported on macOS"	Wrong platform	Use full screen capture
"No windows found"	No permissions	Grant screen recording permission
"Failed to list windows"	System error	Check permissions and retry

Related Tools

• take_screenshot - Capture screenshots
• get_last_screenshot - Retrieve recent screenshots

Limitations

• macOS only due to platform APIs
• Requires native Swift utilities
• Cannot list minimized windows
• Some system windows are filtered out
• No window manipulation capabilities