# AInotate

> AInotate is an open-source MCP server for design and media. Annotated screenshots for AI agents: numbered steps, arrows, boxes and solid redaction. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** macOS, Linux, Windows, CLI, self-hosted
- **Website:** https://www.dontpayfull.com/labs/ainotate/
- **Repository:** https://github.com/dontpayfull/ainotate
- **MCP Registry name:** io.github.dontpayfull/ainotate
- **Categories:** design and media, developer tools
- **Listing updated:** 2026-11-15

## About

When an agent is asked where a setting lives, this server answers with the screen itself: it captures a web page, a window or an existing image, finds the control, and draws a numbered step beside it. It maps the text and icons on the page and places each label in free space near its target, with arrows that curve around content they would cover, then looks at the result before sending it.

It is built for several jobs: bug reports with wrong things in red and correct ones in green, step-by-step guides exported to Markdown, HTML or PDF, before and after plates for UI changes, and handoffs where the person has to act, such as a permission switch, a 2FA code or a payment. In those cases the agent shows what to press and what the click does rather than clicking. Web captures made with `shoot` black out emails and tokens before you see them.

It installs as a PyPI package with Homebrew, pipx or uv, or as plugins for Claude Code, Codex, Gemini CLI and Claude Desktop, and an `ainotate doctor` command checks screen permission, the browser and OCR. The project is free and open source and runs on your machine.

## Features

- **Page and window capture:** Captures web pages, windows or screenshots you already have.
- **Smart label placement:** Labels sit in free space near targets, with arrows that avoid covering content.
- **Redaction:** Emails and tokens are blacked out in web captures made with the shoot command.
- **Guide export:** `ainotate guide` turns step images into Markdown, HTML or PDF guides.
- **Doctor check:** Checks screen capture permission, browser and OCR and prints fixes.
- **Agent skill:** A bundled skill tells the agent when to annotate on its own.

## Good for

- Show where a setting is instead of describing it
- Create a step-by-step guide with one image per step
- Attach annotated screenshots to a bug report
- Mark before and after states for a changelog
- Show exactly what to click at a consent or payment screen

## Install

### Claude Code (Terminal)

```sh
claude mcp add ainotate -- uvx ainotate
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "ainotate": {
      "command": "uvx",
      "args": [
        "ainotate"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "ainotate": {
      "command": "uvx",
      "args": [
        "ainotate"
      ]
    }
  }
}
```

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

```json
{
  "servers": {
    "ainotate": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "ainotate"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "ainotate": {
      "command": "uvx",
      "args": [
        "ainotate"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "ainotate": {
      "command": "uvx",
      "args": [
        "ainotate"
      ]
    }
  }
}
```

## Tools

- `doctor`: Checks screen capture permission, the browser and OCR and prints fixes for anything missing.

## FAQ

### Is it free?

Yes, the site describes it as free and open source and it runs on your machine.

### Which agents does it work with?

Claude Code, Cowork, Claude Desktop, Codex, Gemini CLI, Cursor and other MCP clients.

### What do I need installed?

Python 3.10 or newer via pipx or uv, or Homebrew on macOS; web capture needs Chromium.

### Does the agent click for me?

For steps like permissions, 2FA codes or payments it shows what to press rather than clicking.

### Is AInotate free?

Yes. AInotate is open source, so you can use and self-host it for free.

### How do I add AInotate to Claude Code?

Run this command in your terminal: claude mcp add ainotate -- uvx ainotate

### What are the best alternatives to AInotate?

The closest alternatives to AInotate are REA, HyperFrames by HeyGen, Codebase Memory, GitHub and Serena MCP: the IDE for your agent.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.
- [ffmpeg-skill](https://ai-powered.com/mcp/ffmpeg-skill): ffmpeg-skill is an open-source MCP server for design and media.
- [Ouroboros](https://ai-powered.com/mcp/ouroboros): Ouroboros is an open-source MCP server for developer tools.

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