Tool Reference

The QuikGIF MCP server exposes 21 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. Resolves to the first matching window; when several match, check `target`/`other_matches` in the response or pass `window_id` to disambiguate
`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,
  "target": {
    "window_id": 12345,
    "title": "Animation - Wikipedia",
    "app": "Google Chrome",
    "frame": { "x": 0, "y": 25, "w": 1512, "h": 900 }
  },
  "other_matches": 3
}

target names the window that was actually selected, and other_matches is how many other windows matched an app request (0 for an unambiguous window_id). With a multi-window app, confirm target is the window you intended before rendering — a nonzero other_matches means the app name was ambiguous. title and app are omitted when the window reports none.

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`
`frame_diffing`	boolean	No	`false`	Skip encoding unchanged pixels between frames to reduce file size
`format`	string	No	`gif`	Output format: `gif`, `webp`, `apng`, or `mp4`
`release`	boolean	No	`false`	Free the capture's frames after this render instead of retaining it for re-rendering
`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	`true`	Keep the real window title bar (set `false` to crop it)
`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.

Re-rendering the same capture

A capture is retained after rendering, so you can call render_gif again on the same session_id to compare settings - a different max_width, palette_strategy, frame_diffing, format, or set of transforms - without re-recording. Frames are held in memory (decoded, so a 10 s clip is large), and only the most recent few captures are kept; older ones are evicted automatically. Free a capture yourself with release: true on the render call or the discard_recording tool when you are done.

Returns:

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

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
      }
    }
  }
}

`discard_recording`

Release a completed recording's frames to free memory when you are done rendering it. Captures are also evicted automatically once newer ones exceed the retention cap, so this is only needed to reclaim memory sooner.

Parameters:

Name	Type	Required	Default	Description
`session_id`	string	Yes	—	Session ID of the completed recording to discard

Returns:

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

Discarding an already-released capture is not an error - it returns "discarded": false with a note. A still-recording session must be stopped with stop_recording first.

`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​

discard_recording​

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`

`discard_recording`

`process_gif`

Utility Tools

`list_settings`

`list_commands`

`check_permissions`