@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 and configures each one automatically. Restart the client — a browser window will open for OAuth authorization on first use.

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)
• Adds Vidalytics as an MCP server in each detected client's config
• Shows a preview of changes and asks for confirmation before writing anything

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 |

Options

npx @vidalytics/mcp install [flags]

  --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 confirmation prompt

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" |

Requirements

• Node.js 18+
• A Vidalytics account

License

MIT