# shotlog

> shotlog is an open-source MCP server for productivity. Capture macOS windows into a numbered, captioned screenshot log and report. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** macOS, CLI
- **Repository:** https://github.com/marlon-trujillo-jaramillo/shotlog-mcp
- **MCP Registry name:** io.github.Marlon-Trujillo-Jaramillo/shotlog-mcp
- **Categories:** [productivity](https://ai-powered.com/categories/productivity), [files and documents](https://ai-powered.com/categories/files-and-documents)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

```sh
claude mcp add shotlog-mcp -- uvx shotlog-mcp
```

### Claude Desktop (claude_desktop_config.json)

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

### Cursor (~/.cursor/mcp.json)

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

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "shotlog-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "shotlog-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

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

### Other clients (your client's MCP settings (most use this shape))

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

## Tools

- `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.

## 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.

## Alternatives

- [Ha MCP](https://ai-powered.com/mcp/ha-mcp): Ha MCP is an open-source MCP server for productivity.
- [Concord MCP](https://ai-powered.com/mcp/concord-mcp): Concord MCP is a freemium MCP server for developer tools.
- [note1](https://ai-powered.com/mcp/note1): note1 is an MCP server for productivity.
- [SSRS2](https://ai-powered.com/mcp/ssrs2): SSRS2 is an MCP server for files and documents.
- [Csv](https://ai-powered.com/mcp/csv): Csv is a freemium MCP server for files and documents.
- [Zovo Spreadsheet Compare](https://ai-powered.com/mcp/zovo-spreadsheet-compare): Zovo Spreadsheet Compare is an MCP server for files and documents.
- [Jira](https://ai-powered.com/mcp/jira): Jira is a freemium MCP server for productivity.
- [InviteKit Calendar Files](https://ai-powered.com/mcp/invitekit-calendar-files): InviteKit Calendar Files is an MCP server for files and documents.

---
Source: https://ai-powered.com/mcp/shotlog
