com.vidalytics/mcp
Manage your Vidalytics videos and analytics from your AI assistant.
Open source Repository Open in the app JSON README (API)
About
Manage your Vidalytics videos and analytics from your AI assistant.
Details
- Kind
- MCP servers
- Topic
- Marketing & analytics
- Publisher
- com.vidalytics
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.4.1
- Last push
- 2026-08-27T07:00:44Z
- Repository state
- ativo
- Language
- JavaScript
- License
- MIT
- Added
- 2026-08-29 03:01:26
- Updated
- 2026-08-29 03:01:26
- Origin id
com.vidalytics/mcp
README
# @vidalytics/mcp
[](https://www.npmjs.com/package/@vidalytics/mcp)
[](https://github.com/vidalytics/vidalytics-mcp/actions/workflows/ci.yml)
[](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
[](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)