Skip to content
MCP server

shotlog

Capture macOS windows into a numbered, captioned screenshot log and report

Runs locallyStatus and history
Install
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-mcp

Add to claude_desktop_config.json

{
  "mcpServers": {
    "shotlog-mcp": {
      "command": "uvx",
      "args": [
        "shotlog-mcp"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "shotlog-mcp": {
      "command": "uvx",
      "args": [
        "shotlog-mcp"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

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.

How AIPoweredBot checks servers