MCP tools reference¶

The MCP server (screensight-mcp) exposes nine tools over stdio. Unlike the CLI, the capture tools return MCP Image/Audio content blocks rather than file paths, so the calling agent looks at the frame (or listens to the audio) in its own context instead of reading a file off disk.

Tool	Description
`screen_enable`	Turn ON the master switch
`screen_disable`	Turn OFF the master switch
`screen_status`	Check whether capture is enabled
`screen_capture`	Capture screen, returns image + window title
`screen_capture_audio`	Record system audio, returns audio block
`screen_watch_start`	Start the bounded watch daemon
`screen_watch_stop`	Stop the watch daemon
`screen_watch_latest`	Daemon status and frame count
`screen_list_displays`	List available monitors

screen_enable¶

Turn on the master switch. Must be called before any capture succeeds.

Input: none
Output: "ScreenSight enabled. State: {'enabled': True, ...}"

screen_disable¶

Turn off the master switch. Stops any running watch daemon and deletes the frame.

Input: none
Output: "ScreenSight disabled. State: {'enabled': False, ...}"

screen_status¶

Check whether the master switch is on or off.

Input: none
Output: "ScreenSight is ON. Details: {'enabled': True, ...}"

screen_capture¶

Capture the screen and return the image to the agent.

Input:
  - question (optional): text echoed back for context
  - display  (optional): display index; omit for primary
Output: Image content block + text with window title, path and hash

Ask your agent "what's on my screen?" and it will call this tool, receive the image, and describe what it sees.

The switch is enforced below this tool

screen_capture calls core.capture_once(), which re-reads the master switch and the blocklist itself. No tool description, prompt or injected instruction can talk the server into capturing while the switch is off.

screen_capture_audio¶

Record the system's audio output (loopback) and return it to the agent.

Input:
  - duration (default 5):  seconds to record (clamped to 1–30)
  - question (optional):   text echoed back for context
Output: Audio content block (WAV) + text with duration, sample rate and path

Opt-in and off by default. Beyond the master switch, audio requires the SCREENSIGHT_ENABLE_AUDIO=1 environment variable, and the server must be installed with the audio extras (pip install 'screensight[audio]'). If either is missing, the tool returns a clear Audio capture failed: ... message rather than recording.

Loopback works out of the box on Windows (WASAPI) and Linux (PulseAudio/PipeWire monitor); macOS and WSL need a virtual output device (BlackHole/SoundFlower). The audio.wav file is deleted on screen_disable.

The switch is enforced below this tool

Like screen_capture, this tool calls into core.capture_audio(), which re-checks the master switch and the SCREENSIGHT_ENABLE_AUDIO gate itself — no prompt can talk the server into recording while either is off.

screen_watch_start¶

Start a detached background daemon that captures on an interval.

Input:
  - interval   (default 5):  seconds between captures
  - max_frames (default 10): changed frames before auto-stop
Output: "Watch daemon started: {'running': True, 'pid': 12345, ...}"

screen_watch_stop¶

Stop the running daemon.

Input: none
Output: "Watch daemon stopped: {'running': False, ...}"

screen_watch_latest¶

Poll the daemon's progress.

Input: none
Output:
  Daemon running: True
  Status: running
  Frames analyzed: 3
  Last hash: 15dc34902d50...
  Interval: 5s
  Max frames: 10

screen_list_displays¶

List available monitors, so screen_capture can target one by index.

Input: none
Output:
  Available displays:
    Display 0: primary (1920x1080)
    Display 1: secondary (2560x1440)

Running the server directly¶

screensight-mcp                          # stdio server, for an agent to spawn
fastmcp dev screensight.mcp_server:mcp   # dev inspector

Configuration snippets for each agent are in Agent setup.