Vidalytics

@vidalytics/mcp

[npm version] [CI] [license]

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

[Add Vidalytics to 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 the tools below.

Many write tools (settings, chapters, captions, tags, CTAs, pause screens, thumbnails) save changes to the video's draft — call publish_video to make them live. Write tools require a read+write authorization; a read-only connection returns SCOPE_INSUFFICIENT.

Previewing changes. update_video_settings accepts dryRun to validate and return a before/after diff without saving. The other draft-based writes have no dryRun; preview them by saving to the draft and reading it back with the matching get_*/list_* tool (e.g. get_video_chapters, get_video_tags, get_video_captions) before you publish_video. A delete that only removes an unpublished draft edit is likewise reversible until publish; a delete against already-published content takes effect on the next publish.

Videos & metadata

Analytics

Chapters, captions & tags

CTAs & pause screens

Thumbnails

Folders & settings templates

Uploads

Account

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:

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