shotlog-mcp
Provides tools for listing visible macOS windows, capturing a chosen window as a numbered screenshot with a caption, managing captions, and exporting the screenshot log into a Markdown report.
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.

What it does
Tool | Description |
| Lists the visible windows (app, title, size). |
| Captures one window, picked by app and/or title (front-most by default), and saves it as |
| Fills in or fixes the caption afterwards. |
| Shows the log in order. |
| Fetches new screenshots from another machine (e.g. Windows' |
| Writes |
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-mcpClaude 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 | |
|
| Where screenshots, |
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.pdfDevelopment
uv run --group dev pytestLicense
MIT
Available Tools
6 toolsexport_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
Scored across 6 tools
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.
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.
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.
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
Related MCP Connectors
Your AI apps as one team: hand work to Codex or Claude Code on your Mac, with a shared logbook.
Free Markdown notes app, Mac and iPhone. Sync ($5.99/mo) adds a personal MCP endpoint for your AI.
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Turn screen recordings into step-by-step guides, SOPs, tutorials and user docs with screenshots.
Related MCP Servers
- AlicenseAqualityAmaintenanceA macOS utility that captures screenshots and analyzes them with AI vision, enabling AI assistants to see and interpret what's on your screen.32,020 npm5,494MIT
- AlicenseAqualityDmaintenanceEnables 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.323 npm2MIT
- AlicenseNot gradedqualityDmaintenanceScreenshot 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 npm352MIT
- AlicenseNot gradedqualityCmaintenanceLocal-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