shotlog
Capture macOS windows into a numbered, captioned screenshot log and report
- Pricing
- Open source
- Platforms
- macOS, CLI
- Runs
- Locally
- Version
- 0.1.1
- Listing updated
- today
Similar MCP servers
About shotlog
shotlog is an open-source MCP server for productivity. It runs locally on your machine and is started by your AI client.
Built for a university OS lab where every step needed a screenshot, shotlog saves one window at a time as a sequentially numbered PNG (such as 001_name.png) with a caption covering the activity, command and result. An assistant can run a command in the terminal, capture that window and caption it as a given step in one request.
The log lives in a single folder, set with the SHOTLOG_DIR variable (default ~/shotlog), alongside a manifest.json. Exporting writes a report.md with every screenshot and caption in order, which the README says can be turned into a PDF with pandoc. An optional tool pulls new screenshots from another machine over SCP, such as a Windows laptop's screenshots folder, and numbers them in the same sequence; that needs an SSH server and key-based login on the other machine.
It is macOS only, needs Python 3.11 or newer and uv, and the first capture requires Screen Recording permission for the app running the server. The package is MIT licensed.
Install
Run in a terminal
claude mcp add shotlog-mcp -- uvx shotlog-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"shotlog-mcp": {
"command": "uvx",
"args": [
"shotlog-mcp"
]
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"shotlog-mcp": {
"command": "uvx",
"args": [
"shotlog-mcp"
]
}
}
}Add to .vscode/mcp.json
{
"servers": {
"shotlog-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"shotlog-mcp"
]
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"shotlog-mcp": {
"command": "uvx",
"args": [
"shotlog-mcp"
]
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"shotlog-mcp": {
"command": "uvx",
"args": [
"shotlog-mcp"
]
}
}
}Using several servers? Build one config file with the MCP config generator.
Configuration
SHOTLOG_DIRFolder for screenshots, manifest.json and report.md (default: ~/shotlog)
Tools this server provides (6)
Taken from the project documentation; the running server may differ.
- list_windows
- Lists visible windows with app, title and size.
- save_screenshot
- Captures one window and saves it with a number and caption.
- update_caption
- Fills in or fixes a caption afterwards.
- list_screenshots
- Shows the log in order.
- pull_remote_screenshots
- Fetches new screenshots from another machine over SCP.
- export_report
- Writes report.md with every screenshot and caption in order.
What it does
- Single-window capture
- Captures one window picked by app or title, front-most by default.
- Numbered log
- Saves each shot with a sequence number and caption.
- Caption editing
- Fills in or corrects captions after the capture.
- Remote screenshot pull
- Fetches new screenshots from another machine over SCP into the same sequence.
- Markdown report
- Exports every screenshot and caption in order to report.md.
- Per-project folders
- Point SHOTLOG_DIR at a separate folder for each project.
Good for
- Document lab steps with a screenshot for each command
- Collect QA evidence for a test run
- Build screenshot-based tutorials or runbooks
- Attach captioned captures to bug reports
Pricing
Open source
MIT licensed
shotlog FAQ
Which operating systems does it run on?
macOS only, with Python 3.11+ and uv. It can pull screenshots from another machine such as Windows over SCP.
What permission does it need?
Screen Recording permission for the app that runs the server, such as Terminal, VS Code or Claude.
Where are files saved?
In ~/shotlog by default, or the folder set in SHOTLOG_DIR.
How do I get a PDF?
Export report.md, then run pandoc report.md -o report.pdf in the folder.
Is shotlog free?
Yes. shotlog is open source, so you can use and self-host it for free.
How do I add shotlog to Claude Code?
Run this command in your terminal: claude mcp add shotlog-mcp -- uvx shotlog-mcp
What are the best alternatives to shotlog?
The closest alternatives to shotlog are Ha MCP, Concord MCP, note1, SSRS2 and Csv.
Where this comes from
- Description: written from the project's README.
- Install steps: from the official MCP Registry entry.
