# @vidalytics/mcp

[![npm version](https://img.shields.io/npm/v/@vidalytics/mcp)](https://www.npmjs.com/package/@vidalytics/mcp)
[![CI](https://github.com/vidalytics/vidalytics-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/vidalytics/vidalytics-mcp/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/@vidalytics/mcp)](LICENSE)

One-command setup that connects your AI coding assistant to Vidalytics video analytics data via the [Model Context Protocol](https://modelcontextprotocol.io).

Works with Claude (CLI & Desktop), Windsurf, Cursor, and any other MCP-compatible client.

## Setup

```bash
npx @vidalytics/mcp install
```

That's it. The installer detects which AI clients you have installed, lets you **pick which ones to configure**, and wires them up. Restart the client — a browser window will open for OAuth authorization on first use.

## Cursor

[![Add Vidalytics to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=vidalytics&config=eyJ0eXBlIjoiaHR0cCIsInVybCI6Imh0dHBzOi8vYXBpLnZpZGFseXRpY3MuY29tL3B1YmxpYy92MS9tY3AifQ%3D%3D)

**Or via the installer:**

```bash
npx @vidalytics/mcp install --client cursor
```

**Or manually** — add this to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "vidalytics": {
      "url": "https://api.vidalytics.com/public/v1/mcp"
    }
  }
}
```

Restart Cursor. On first use a browser window opens for OAuth authorization with your Vidalytics account — no API key or environment variables to set.

## What it does

- Detects installed MCP clients (Claude CLI, Claude Desktop, Windsurf, Cursor) by checking config files, app directories, binaries in `$PATH`, and app bundles (e.g. `/Applications` on macOS)
- Presents an interactive checklist (detected clients pre-selected) so you configure exactly the ones you want — or pick them non-interactively with `--client`
- Adds Vidalytics as an MCP server in each selected client's config
- Verifies after writing: the config is valid and the MCP server is reachable
- Non-interactive terminals (CI) and any explicit selection flag (`--client`, `--all`, `--yes`) skip the checklist and behave predictably

## Available tools

Once connected, your AI assistant gains access to:

| Tool | Description |
|------|-------------|
| `set_user_context` | MUST be called before any other tool to enable analytics |
| `list_videos` | List videos with pagination |
| `get_video` | Get video details |
| `get_video_by_embed_guid` | Find a video by its embed GUID |
| `update_video` | Update a video's title or folder |
| `get_video_embed` | Get the embed code and configuration |
| `get_video_settings` | Get playback settings (autoplay, controls, etc) |
| `get_video_thumbnail` | Get the thumbnail image URL |
| `get_video_stats` | Views, play rate, watch time, conversions |
| `get_video_dropoff` | Audience retention by percentage |
| `get_video_percentage_watched` | % of viewers who reached each point |
| `get_video_live_metrics` | Real-time active viewers and watch rate |
| `get_video_ctas` | Get CTAs for a video |
| `get_video_pause_screens` | Get pause screens for a video |
| `get_videos_stats_batch` | Stats for up to 30 videos at once |
| `get_videos_timeline` | Timeline stats for up to 5 videos |
| `list_folders` | List video folders |
| `list_settings_templates` | List settings templates |
| `get_api_usage` | Get current API usage and quota |
| `list_connections` | List apps connected to your account |
| `revoke_connection` | Disconnect an app or yourself |
| `upload_video_from_url` | Upload a video from a remote URL |
| `get_video_upload_url` | Get a signed URL for local file upload |
| `validate_upload` | Complete a direct video upload |
| `publish_video` | Publish a video's pending draft settings |
| `duplicate_video` | Duplicate a video and publish the copy |
| `create_folder` | Create a video folder, optionally nested under another folder |
| `apply_settings_template` | Apply a reusable player settings template to a video |
| `create_video_cta` | Create a call-to-action on a video |
| `update_video_cta` | Update an existing call-to-action on a video |
| `set_video_thumbnail_from_url` | Set a video's thumbnail from a public image URL |
| `set_video_thumbnail_from_frame` | Set a video's thumbnail from one of its frames |
| `delete_video_thumbnail` | Remove a custom thumbnail and restore the default |

## Options

```
npx @vidalytics/mcp install [flags]

  --client <names>   Configure only these clients, comma-separated
                     (claude-cli, claude-desktop, windsurf, cursor)
  --all              Configure all known clients, even if not detected
  --config <path>    Also configure a custom config file (repeatable)
  --force            Re-apply even if already configured
  --yes              Skip prompts (configure detected clients)
```

Run with no flags in an interactive terminal to get a checklist of clients to configure (detected ones are pre-selected; use space to toggle, enter to confirm). `--client cursor,windsurf` does the same selection non-interactively.

The `--config` flag can be repeated for multiple files. The target file must follow the `{ "mcpServers": {} }` format used by Claude Desktop, Cursor, and Windsurf — useful for unsupported clients like Zed or VS Code with an MCP plugin.

## Troubleshooting

**Authorization issues, or need to re-authenticate?** Reset the credentials that
`mcp-remote` caches in your home directory, then restart the client:

| OS | Command |
|----|---------|
| macOS / Linux | `rm -rf ~/.mcp-auth` |
| Windows (CMD) | `rd /s /q "%USERPROFILE%\.mcp-auth"` |
| Windows (PowerShell) | `Remove-Item -Recurse -Force "$HOME\.mcp-auth"` |

## MCP Registry

This server is published to the official [MCP Registry](https://registry.modelcontextprotocol.io) as **`com.vidalytics/mcp`**. It is a remote (streamable-http) server, so registry-aware MCP clients can connect to it directly at:

```
https://api.vidalytics.com/public/v1/mcp
```

No API key or environment variables are required — authorization is handled via OAuth on first use.

## Requirements

- Node.js 18+
- A Vidalytics account

## License

[MIT](LICENSE)