# ui-annotator-mcp

Runs a proxy that injects hover overlays onto any web page so AI assistants reference interface elements by exact names.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 21
- Author: mcpware
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mcpware/ui-annotator-mcp
- Updated: 2026-03-24
- HTML: https://affpapa.org/en/nevibecode/mcp/ui-annotator-mcp

## What it does

The server starts a local reverse proxy on port 7077 and serves your web app with an injected annotation script. When you move the pointer over any DOM element, a tooltip reveals its component label, CSS selector, dimensions, and text content. This gives both you and your assistant a shared reference for edits.

Setup needs neither browser add-ons nor edits to your source tree. An inspect mode halts link clicks and copies component titles directly to your clipboard upon selection. AI clients access tools like `annotate`, `get_elements`, and `highlight_element` to inspect the layout or flash targeted nodes on the screen.

Routing requires accessing the app through the proxy path, such as `http://localhost:7077/localhost:3847`. Without the target local process actively listening on that destination port, the proxy cannot fetch the markup or return structured nodes to the model.

## Requirements
- Needs: Node.js (commands run via npx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add ui-annotator-mcp -- npx -y @mcpware/ui-annotator
```

### Codex

**Platform CLI**
```bash
codex mcp add ui-annotator-mcp -- npx -y @mcpware/ui-annotator
```

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "ui-annotator-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@mcpware/ui-annotator"
            ]
        }
    }
}
```

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "ui-annotator-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@mcpware/ui-annotator"
            ]
        }
    }
}
```

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add ui-annotator-mcp npx -y @mcpware/ui-annotator
```

## When to use it
- Identify interface components using hover tooltips in any browser
- Share structured DOM nodes and technical selectors with an AI agent
- Copy element identifiers to the clipboard in inspect mode
- Highlight specific page nodes visually during design iterations

## Example prompts
- Annotate the page at localhost:3847 and list all detected components
- Toggle inspect mode and highlight the SearchButton element
- Make the sidebar container 40 pixels wider after rescanning the DOM

## Similar
- [Front-End Checklist](https://affpapa.org/en/nevibecode/mcp/front-end-checklist.md) — MCP server · ★ 74559
- [tldraw](https://affpapa.org/en/nevibecode/mcp/tldraw.md) — MCP server · ★ 51091
- [Figma-Context-MCP](https://affpapa.org/en/nevibecode/mcp/figma-context-mcp.md) — MCP server · ★ 16062
- [mcp-server-chart](https://affpapa.org/en/nevibecode/mcp/mcp-server-chart.md) — MCP server · ★ 4402
- [Dembrandt](https://affpapa.org/en/nevibecode/mcp/dembrandt.md) — MCP server · ★ 3821
- [RevoGrid DataGrid MCP Pro](https://affpapa.org/en/nevibecode/mcp/revogrid-datagrid-mcp-pro.md) — MCP server · ★ 3450

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md