# Annotate MCP install

Install **Annotate MCP** (`annotate-session`) so your agent can query private Annotate recording sessions on this Mac.

**Annotate MCP is a local stdio MCP server.** It is not a remote/cloud MCP. It ships with the Annotate Mac app and runs together with the app — launch Annotate at least once so the MCP bundle exists under Annotate’s app data.

Follow the section for the agent you are currently running (or the agent named in the user’s install prompt). After install, reload MCP and confirm Annotate tools work (e.g. `list_sessions` or `get_timeline`).

If the user pasted an Annotate **install prompt** with an absolute MCP entry path, **prefer that path** over the defaults below.

Do **not** set an `ANNOTATE_DATA_DIR` (or similar) environment variable. The server locates Annotate’s private library from a `data-root.json` sidecar beside the installed MCP bundle (or from the install path / platform default). Use `list_sessions` if you need `dataDir`, `sessionsRoot`, or `framesRoot`.

## Prerequisites

1. **Annotate** for Mac is installed on this machine.
2. Annotate has been launched at least once (so the local MCP bundle exists and can run with the app).
3. **Node.js** is available on `PATH` (`node`).

Default MCP entry (stdio server, macOS):

`~/Library/Application Support/Annotate/mcp/annotate-session/index.js`

Expand `~` to an absolute path in config files.

## Shared server config (JSON clients)

Use this shape for Cursor, Claude Desktop, Claude Code, and other JSON `mcpServers` clients. Replace the entry path with the absolute value from the user’s install prompt when present. Omit any `env` block.

```json
{
  "mcpServers": {
    "annotate-session": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/Annotate/mcp/annotate-session/index.js"
      ]
    }
  }
}
```

## Cursor

1. Open or create `~/.cursor/mcp.json`.
2. Merge the shared `mcpServers.annotate-session` entry above (create the file if needed).
3. Reload MCP in Cursor (or restart Cursor).
4. Confirm Annotate tools are available (e.g. `list_sessions` or `get_timeline`).

## Claude Desktop

Config file (macOS): `~/Library/Application Support/Claude/claude_desktop_config.json`

1. Merge the same `mcpServers.annotate-session` entry (no `env`).
2. Fully quit and relaunch Claude Desktop (or: Settings → Developer → Edit Config, save, restart).
3. Confirm Annotate tools are available.

## Claude Code

Prefer the CLI (user scope, all projects). Substitute the absolute MCP entry from the install prompt:

```bash
claude mcp add --scope user annotate-session -- node /ABSOLUTE/PATH/TO/Annotate/mcp/annotate-session/index.js
```

Or merge the shared JSON `mcpServers` entry into `~/.claude.json` (top-level `mcpServers`), then restart Claude Code / reload MCP.

## Codex

Codex uses TOML, not JSON. Edit `~/.codex/config.toml` (create if needed) and add:

```toml
[mcp_servers.annotate-session]
command = "node"
args = ["/ABSOLUTE/PATH/TO/Annotate/mcp/annotate-session/index.js"]
```

The top-level key must be `mcp_servers` (underscore). Do not add an `env` / `ANNOTATE_DATA_DIR` table. After saving, start a Codex session and confirm Annotate tools are connected (e.g. `/mcp`).

## After install

**Annotate MCP is required** to understand a recording. If tools are missing: stop, ask the user for approval, install using the section for your current agent, reload MCP, then continue.

When the user shares a `Session id`:

1. Call **`get_timeline`** first.
2. Use **`search_session`** for keywords.
3. Fetch capped slices with **`get_frames_near`** / **`get_transcript_range`** as needed.
4. Focus on screen content, annotations, and speech — not capture architecture unless asked.