take_screenshot

Take a screenshot and return it as base64 encoded PNG data.

Overview

The take_screenshot tool captures screenshots of your screen or specific windows (macOS only). Screenshots are saved to a configurable directory and returned as base64 encoded PNG images for immediate use.

Purpose

• Visual Documentation: Capture UI states for documentation
• Debugging: Take screenshots during development to debug visual issues
• Testing: Capture test results and UI states
• Design Review: Share visual states with team members
• Error Reporting: Capture error states visually

Input Schema

{
  "type": "object",
  "properties": {
    "windowId": {
      "type": "number",
      "description": "Optional window ID to capture specific window (macOS only)"
    }
  }
}

Parameters

windowId (optional)

• Type: number
• Description: Window ID to capture a specific window
• Platform: macOS only
• Note: Use list_windows tool first to get available window IDs

Output

Returns an object with screenshot information and base64 encoded image:

{
  "content": [
    {
      "type": "text",
      "text": "Screenshot taken: /path/to/screenshot.png"
    },
    {
      "type": "image",
      "data": "base64encodedpngdata...",
      "mimeType": "image/png"
    }
  ]
}

Platform Support

Platform	Full Screen	Window Capture
macOS	✅	✅
Linux	✅	❌
Windows	✅	❌

Examples

Take Full Screen Screenshot

const result = await take_screenshot({});

Capture Specific Window (macOS)

// First, list available windows
const windows = await list_windows({});

// Then capture a specific window
const result = await take_screenshot({
  windowId: 5  // Window ID from list_windows
});

Configuration

Set the screenshot directory using environment variable:

export ORCHESTRE_SCREENSHOT_PATH="/path/to/screenshots"

Default: ~/Desktop/orchestre-screenshots

Use Cases

1. Document UI Changes

// Before making changes
await take_screenshot({});

// Make UI changes
// ...

// After changes
await take_screenshot({});

2. Capture Error States

try {
  // Some operation that might fail visually
} catch (error) {
  // Capture the error state
  await take_screenshot({});
}

3. Window-Specific Capture

// Find the browser window
const windows = await list_windows({});
const browser = windows.find(w => w.app.includes('Chrome'));

// Capture just the browser
await take_screenshot({
  windowId: browser.id
});

Permissions

macOS

• Screen Recording Permission: Required for screenshots
• Grant in: System Preferences → Security & Privacy → Privacy → Screen Recording

Linux

• Requires gnome-screenshot or scrot package

Windows

• Uses PowerShell with .NET Framework (built-in)

Error Handling

Common errors and solutions:

Error	Cause	Solution
"Screenshot path is not writable"	Directory permissions	Check directory permissions
"Window with ID X not found"	Invalid window ID	Use list_windows to get valid IDs
"Window-specific screenshots are only supported on macOS"	Platform limitation	Use full screen capture instead
"Failed to take screenshot"	Missing permissions	Grant screen recording permission

Best Practices

1. Check Platform: Window capture only works on macOS
2. List Windows First: Always use list_windows before window-specific capture
3. Handle Errors: Screenshots can fail due to permissions
4. Clean Up: Regularly clean screenshot directory
5. Security: Be aware screenshots may contain sensitive information

Related Tools

• get_last_screenshot - Retrieve the most recent screenshot
• list_windows - List available windows for capture

Limitations

• Window capture requires macOS with screen recording permissions
• Screenshots are stored locally, not uploaded anywhere
• Large screenshots may take time to encode as base64
• No built-in image editing capabilities