Tool Reference

The QuikGIF MCP server exposes 19 tools organized into six categories.

Script Tools

`execute_script`

Execute a .qgif script to generate a GIF demo. Provide either inline script source or a file path.

Parameters:

Name	Type	Required	Default	Description
`script`	string	One of `script`/`file`	—	Inline `.qgif` script source code
`file`	string	One of `script`/`file`	—	Path to a `.qgif` script file
`preview`	boolean	No	`false`	Render a quick low-res preview (10fps, 400px)

Returns:

{ "path": "demo.gif", "size_mb": 1.2 }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "execute_script",
    "arguments": {
      "script": "set output \"demo.gif\"\nopen \"Terminal\"\ncapture-window app \"Terminal\" as $t\nrecord $t duration 3 continue\ntype \"echo Hello\" enter\nremain\nrender"
    }
  }
}

`validate_script`

Validate a .qgif script without executing it. Returns syntax errors and warnings.

Parameters:

Name	Type	Required	Default	Description
`script`	string	One of `script`/`file`	—	Inline `.qgif` script source code
`file`	string	One of `script`/`file`	—	Path to a `.qgif` script file

Returns (valid):

{ "valid": true, "instruction_count": 8, "warnings": [] }

Returns (invalid):

{ "valid": false, "error": "Line 3: Unknown command 'recrd'", "warnings": [] }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "validate_script",
    "arguments": {
      "script": "open \"Terminal\"\nrecord $t duration 3\nrender"
    }
  }
}

Window Management Tools

`list_windows`

List all capturable windows on screen. Optionally filter by application name.

Parameters:

Name	Type	Required	Default	Description
`app`	string	No	—	Filter by application name (case-insensitive substring match)

Returns:

{
  "windows": [
    { "id": 12345, "app": "Terminal", "title": "zsh", "x": 100, "y": 200, "width": 800, "height": 600 },
    { "id": 12346, "app": "Terminal", "title": "bash", "x": 150, "y": 250, "width": 800, "height": 600 }
  ]
}

Example:

{
  "method": "tools/call",
  "params": {
    "name": "list_windows",
    "arguments": { "app": "Terminal" }
  }
}

`open_app`

Open an application and return the new window ID. Creates a new window even if the app is already running.

Parameters:

Name	Type	Required	Default	Description
`app`	string	Yes	—	Application name (e.g. "Terminal", "Finder", "Safari")

Returns:

{ "window_id": 12345, "app": "Terminal", "title": "zsh" }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "open_app",
    "arguments": { "app": "Terminal" }
  }
}

`focus_app`

Bring an application to the front.

Parameters:

Name	Type	Required	Default	Description
`app`	string	Yes	—	Application name

Returns:

{ "success": true }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "focus_app",
    "arguments": { "app": "Terminal" }
  }
}

Recording Tools

`start_recording`

Start recording a window. Returns a session ID for use with stop_recording and render_gif.

Parameters:

Name	Type	Required	Default	Description
`window_id`	integer	One of `window_id`/`app`	—	Window ID from `list_windows`
`app`	string	One of `window_id`/`app`	—	Application name (uses first matching window)
`crop`	object	No	—	Sub-region `{ x, y, w, h }` relative to window content area
`fps`	integer	No	`30`	Frame rate
`show_cursor`	boolean	No	`true`	Include cursor in recording
`duration`	number	No	—	Auto-stop after N seconds

Returns:

{ "session_id": "rec-a1b2c3d4", "recording": true }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "start_recording",
    "arguments": { "app": "Terminal", "fps": 30, "duration": 5 }
  }
}

info

The crop object specifies a sub-region relative to the window's content area (below the title bar). All four fields (x, y, w, h) are required when using crop.

`record_region`

Record a screen region by absolute coordinates.

Parameters:

Name	Type	Required	Default	Description
`x`	integer	Yes	—	X coordinate of region origin
`y`	integer	Yes	—	Y coordinate of region origin
`width`	integer	Yes	—	Region width in points
`height`	integer	Yes	—	Region height in points
`fps`	integer	No	`30`	Frame rate
`show_cursor`	boolean	No	`true`	Include cursor in recording
`duration`	number	No	—	Auto-stop after N seconds

Returns:

{ "session_id": "rec-e5f6g7h8", "recording": true }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "record_region",
    "arguments": { "x": 100, "y": 200, "width": 800, "height": 600, "duration": 5 }
  }
}

`stop_recording`

Stop an active recording session. Frames are preserved for render_gif.

Parameters:

Name	Type	Required	Default	Description
`session_id`	string	Yes	—	Session ID from `start_recording` or `record_region`

Returns:

{ "session_id": "rec-a1b2c3d4", "frames": 150, "elapsed": 5.0 }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "stop_recording",
    "arguments": { "session_id": "rec-a1b2c3d4" }
  }
}

`pause_recording`

Cancel the auto-stop timer on an active recording.

Parameters:

Name	Type	Required	Default	Description
`session_id`	string	Yes	—	Session ID

Returns:

{ "paused": true, "frames": 90, "note": "Capture stream continues running. For true pause, use stop_recording + start_recording." }

warning

SCStream does not support native pause/resume. The capture stream continues running during "pause" — frames captured during the paused period will be included when stop_recording is called. For a true pause, use stop_recording followed by start_recording to create separate segments.

Example:

{
  "method": "tools/call",
  "params": {
    "name": "pause_recording",
    "arguments": { "session_id": "rec-a1b2c3d4" }
  }
}

`resume_recording`

Acknowledge resume after pause. Since pause does not stop capture, this is informational only.

Parameters:

Name	Type	Required	Default	Description
`session_id`	string	Yes	—	Session ID

Returns:

{ "resumed": true, "note": "Recording continues. Use stop_recording when done." }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "resume_recording",
    "arguments": { "session_id": "rec-a1b2c3d4" }
  }
}

Input Simulation Tools

`type_text`

Simulate typing text with human-like pacing.

Parameters:

Name	Type	Required	Default	Description
`text`	string	Yes	—	Text to type
`enter`	boolean	No	`false`	Press Enter after typing
`delay`	number	No	`0.05`	Per-character delay in seconds

Returns:

{ "success": true }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "type_text",
    "arguments": { "text": "git status", "enter": true }
  }
}

`click`

Click at screen coordinates. If x/y are omitted, clicks at the current cursor position.

Parameters:

Name	Type	Required	Default	Description
`x`	number	No	Current position	X screen coordinate
`y`	number	No	Current position	Y screen coordinate
`right`	boolean	No	`false`	Right-click instead of left-click

Returns:

{ "success": true }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "click",
    "arguments": { "x": 400, "y": 300 }
  }
}

`move_cursor`

Move the cursor to a screen position, optionally with smooth animation.

Parameters:

Name	Type	Required	Default	Description
`x`	number	Yes	—	Target X coordinate
`y`	number	Yes	—	Target Y coordinate
`duration`	number	No	`0` (instant)	Smooth animation duration in seconds

Returns:

{ "success": true }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "move_cursor",
    "arguments": { "x": 500, "y": 350, "duration": 0.5 }
  }
}

`key_press`

Press a key with optional modifiers. Use + to combine modifiers with the key.

Parameters:

Name	Type	Required	Default	Description
`key`	string	Yes	—	Key spec (e.g. `enter`, `cmd+c`, `shift+tab`, `ctrl+alt+delete`, `f5`)

Returns:

{ "success": true }

Supported keys: enter/return, tab, space, delete/backspace, escape/esc, up, down, left, right, home, end, pageup, pagedown, f1-f12, a-z

Supported modifiers: cmd/command, shift, alt/option, ctrl/control

Example:

{
  "method": "tools/call",
  "params": {
    "name": "key_press",
    "arguments": { "key": "cmd+c" }
  }
}

`scroll`

Scroll at the current cursor position.

Parameters:

Name	Type	Required	Default	Description
`direction`	string	Yes	—	`up`, `down`, `left`, or `right`
`ticks`	integer	No	`3`	Number of scroll ticks

Returns:

{ "success": true }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "scroll",
    "arguments": { "direction": "down", "ticks": 5 }
  }
}

Rendering Tools

`render_gif`

Render a completed recording session to a GIF file with optional frame transforms.

Parameters:

Name	Type	Required	Default	Description
`session_id`	string	Yes	—	Session ID from `stop_recording`
`output`	string	No	`recording-{id}.gif`	Output file path
`max_width`	integer	No	`800`	Maximum GIF width in pixels
`loop_count`	integer	No	`0`	Loop count (0 = infinite)
`palette_strategy`	string	No	`auto`	Color palette: `auto`, `global`, or `perFrame`
`transforms`	object	No	—	Frame transforms to apply (see below)

Transforms object:

Key	Type	Default	Description
`cursor_smoothing`	boolean	`false`	Smooth cursor movement paths
`click_indicators`	boolean	`false`	Show click overlay effects
`keystroke_badges`	boolean	`false`	Show key combo badges
`type_smoothing`	boolean	`false`	Normalize typing speed
`include_title_bar`	boolean	`false`	Keep window title bar in output
`idle_strategy`	string	—	Idle handling: `cut`, `ramp`, or `fade`
`idle_threshold`	number	`2.0`	Seconds before idle handling kicks in

info

The cursor_smoothing, click_indicators, keystroke_badges, and type_smoothing transforms require Accessibility permission. Without it, they silently have no effect.

Returns:

{ "path": "demo.gif", "size_mb": 1.2, "dimensions": "800x450", "frames": 150 }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "render_gif",
    "arguments": {
      "session_id": "rec-a1b2c3d4",
      "output": "demo.gif",
      "max_width": 800,
      "transforms": {
        "cursor_smoothing": true,
        "keystroke_badges": true
      }
    }
  }
}

`process_gif`

Post-process an existing GIF file. Supports resizing, speed adjustment, and idle handling.

Parameters:

Name	Type	Required	Default	Description
`input`	string	Yes	—	Input GIF file path
`output`	string	No	Overwrite input	Output file path
`max_width`	integer	No	—	Resize to max width
`speed`	number	No	—	Speed multiplier (1.5 = 50% faster, 0.5 = 50% slower)
`idle_strategy`	string	No	—	Idle handling: `cut`, `ramp`, or `fade`
`idle_threshold`	number	No	`2.0`	Idle threshold in seconds
`palette_strategy`	string	No	`auto`	Color palette: `auto`, `global`, or `perFrame`

Returns:

{ "path": "optimized.gif", "size_mb": 0.8, "dimensions": "600x338", "frames": 120 }

Example:

{
  "method": "tools/call",
  "params": {
    "name": "process_gif",
    "arguments": {
      "input": "recording.gif",
      "output": "optimized.gif",
      "max_width": 600,
      "speed": 1.5
    }
  }
}

Utility Tools

`list_settings`

List all available .qgif script settings with their types, defaults, and descriptions.

Parameters: None

Returns:

{
  "settings": [
    { "name": "fps", "type": "int", "default": "30", "description": "Frame rate (12, 24, 30, 60)" },
    { "name": "output", "type": "string", "default": "output.gif", "description": "Output file path" },
    ...
  ]
}

Example:

{
  "method": "tools/call",
  "params": {
    "name": "list_settings",
    "arguments": {}
  }
}

`list_commands`

List all available .qgif script commands with syntax descriptions.

Parameters: None

Returns:

{
  "commands": [
    { "command": "open", "description": "Launch application and create a new window" },
    { "command": "record", "description": "Start recording a window" },
    ...
  ]
}

Example:

{
  "method": "tools/call",
  "params": {
    "name": "list_commands",
    "arguments": {}
  }
}

`check_permissions`

Check current Screen Recording and Accessibility permission status.

Parameters: None

Returns:

{
  "screen_recording": true,
  "accessibility": true,
  "note": "All required permissions granted."
}

When Screen Recording is not granted:

{
  "screen_recording": false,
  "accessibility": false,
  "note": "Screen Recording permission is required. Grant in System Settings > Privacy & Security > Screen Recording."
}

Example:

{
  "method": "tools/call",
  "params": {
    "name": "check_permissions",
    "arguments": {}
  }
}

Script Tools​

execute_script​

validate_script​

Window Management Tools​

list_windows​

open_app​

focus_app​

Recording Tools​

start_recording​

record_region​

stop_recording​

pause_recording​

resume_recording​

Input Simulation Tools​

type_text​

click​

move_cursor​

key_press​

scroll​

Rendering Tools​

render_gif​

process_gif​

Utility Tools​

list_settings​

list_commands​

check_permissions​

Script Tools

`execute_script`

`validate_script`

Window Management Tools

`list_windows`

`open_app`

`focus_app`

Recording Tools

`start_recording`

`record_region`

`stop_recording`

`pause_recording`

`resume_recording`

Input Simulation Tools

`type_text`

`click`

`move_cursor`

`key_press`

`scroll`

Rendering Tools

`render_gif`

`process_gif`

Utility Tools

`list_settings`

`list_commands`

`check_permissions`