Skip to main content
Glama

shotlog-mcp

Let your AI assistant take the screenshots for your report.

An MCP server for macOS. It captures a specific window, saves it with a sequential number and a caption (activity, command, result), and puts everything together into a Markdown report you can turn into a PDF.

It was built for a university OS lab where every step had to be backed by a screenshot, on a Mac and a Windows laptop at the same time. It works the same way for QA evidence, tutorials, runbooks and bug reports.

Leer en español

shotlog demo: the assistant captures a Terminal window as step 1 and exports the report

What it does

Tool

Description

list_windows

Lists the visible windows (app, title, size).

save_screenshot

Captures one window, picked by app and/or title (front-most by default), and saves it as 001_name.png together with its caption.

update_caption

Fills in or fixes the caption afterwards.

list_screenshots

Shows the log in order.

pull_remote_screenshots

Fetches new screenshots from another machine (e.g. Windows' Pictures\Screenshots) over SCP and numbers them in the same sequence.

export_report

Writes report.md: every screenshot with its caption, in order.

Then just ask: "Run ssh -V in the terminal, take a screenshot of it and caption it as step 3."

Related MCP server: PeepIt MCP

Install

Requires macOS, Python 3.11+ and uv.

Claude Code

claude mcp add shotlog -- uvx shotlog-mcp

Claude Desktop / other MCP clients

{
  "mcpServers": {
    "shotlog": { "command": "uvx", "args": ["shotlog-mcp"] }
  }
}

The first capture needs the Screen Recording permission for the app that runs the server (Terminal, iTerm, VS Code, Claude…): System Settings → Privacy & Security → Screen Recording.

Configuration

Variable

Default

SHOTLOG_DIR

~/shotlog

Where screenshots, manifest.json and report.md are saved.

Use one folder per project: claude mcp add shotlog -e SHOTLOG_DIR=~/lab3/shots -- uvx shotlog-mcp

Remote screenshots (optional)

To use pull_remote_screenshots, the other machine needs an SSH server (on Windows: Settings → Optional features → OpenSSH Server) and key-based login from your Mac, so that no password is asked for.

Report to PDF

cd ~/shotlog && pandoc report.md -o report.pdf

Development

uv run --group dev pytest

License

MIT

Available Tools

6 tools
export_reportC

Write report.md in the shotlog folder: every screenshot with its caption, in order. Convert it to PDF/DOCX with any tool (e.g. pandoc).

Inputs: title.

list_screenshotsA

List every logged screenshot with its caption, in order.

Inputs: no named parameters. Returns: result

list_windowsA

List visible windows (id, app, title, size). The first one is the front-most.

Inputs: no named parameters. Returns: result

pull_remote_screenshotsA

Fetch new PNG screenshots from another machine over SCP (e.g. a Windows laptop where Win+PrtScn saves to Pictures\Screenshots) and add them to the log. Requires an SSH server on that machine and key-based auth (no password prompt).

Inputs: host (required), user (required), prefix, remote_dir.

save_screenshotA

Capture ONE macOS window and save it numbered in the shotlog folder.

- name: short slug, e.g. "step1_install".
- app / title_contains: pick the window (e.g. app="Terminal"). Empty = front-most window.
- activity / command / result: caption stored in the manifest and used by export_report.

Inputs: name (required), app, result, command, +2 more.

update_captionC

Fill in or fix the caption (activity, command, result) of a saved screenshot.

Inputs: file (required), result, command, activity.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation4/5

    Each tool maps to a distinct action on a distinct object (live windows, saved screenshots, captions, remote fetch, report export). The only mild overlap is list_windows vs list_screenshots, whose names look similar but whose descriptions clearly separate live window enumeration from logged-entry listing.

    Naming Consistency5/5

    All six tools follow a strict snake_case verb_noun pattern (list_windows, save_screenshot, update_caption, pull_remote_screenshots, list_screenshots, export_report). The verbs (list, save, update, pull, export) accurately signal each operation's semantics.

    Tool Count5/5

    Six tools is well-scoped for a screenshot-logging workflow, covering capture, remote ingest, listing, captioning, and export without redundancy. Every tool earns its place, and there is no bloat.

    Completeness4/5

    The surface covers the core lifecycle: capture (save_screenshot/pull_remote_screenshots), read (list_screenshots/list_windows), edit captions, and export. The notable gaps are a delete/remove operation for logged screenshots and any get-single-screenshot or reorder tool, which agents would otherwise have to work around manually.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI agents to capture and analyze screenshots of macOS applications, windows, or the entire screen using local (Ollama) or cloud-based AI vision models, with non-intrusive, fast screen capture via Apple's ScreenCaptureKit.
      3
      23 npm
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Screenshot and diagram tool for AI agents. Capture and annotate screenshots to show Claude what you mean — or let the agent render Mermaid diagrams and open them for visual review. Approve, annotate, or request changes with text feedback. Built-in review mode with structured responses. CLI and MCP server for Claude Code, Cursor, Windsurf, Cline. macOS, open source, free.
      5 npm
      352
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Local-first memory MCP server that captures macOS screen and app context into persistent Markdown, enabling any tool-capable LLM agent to query its working history.
      MIT