vidalytics

@vidalytics/mcp

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