@vidalytics/mcp

Name: vidalytics mcp
Author: vidalytics

One-command setup that connects your AI coding assistant to Vidalytics video analytics data via the Model Context Protocol.

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

Setup

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

Or via the installer:

npx @vidalytics/mcp install --client cursor

Or manually — add this to ~/.cursor/mcp.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 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