About shotlog
shotlog is a macOS MCP server for AI assistants that need an ordered, captioned record of window screenshots. It collects screenshots into a Markdown report for lab work, QA evidence, tutorials, runbooks and bug reports.
Key features
- 01Capture a selected window
- 02Number and caption screenshots
- 03Edit captions after capture
- 04Import screenshots over SCP
- 05Export an ordered Markdown report
Use cases
- 01Document steps in a university lab
- 02Collect QA evidence
- 03Create screenshot-based tutorials
- 04Prepare runbooks or bug reports
MCP support
The MCP server provides tools to list windows, capture and manage screenshots, import remote screenshots over SCP, and export a Markdown report. It can be connected to MCP clients such as Claude Code and Claude Desktop.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx shotlog-mcpSHOTLOG_DIRFolder for screenshots, manifest.json and report.md (default: ~/shotlog)Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
6Saved tool list · updated 3d ago
This tool takes no parameters.
Details
From the project READMEshotlog-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 |
|---|---|
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."
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
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.