用于 vTurb Analytics API 的 MCP 服务器 — 提供 15 种工具，可直接从 Claude 查询实时和历史视频分析数据。
采用与 hotmart-mcp 相同的模式构建：TypeScript + @modelcontextprotocol/sdk + zod。
15 种分析工具：涵盖会话、事件、互动、点击、转化、流量来源等
内置速率限制器：令牌桶算法，强制执行 Pro 层级 120 次请求/分钟的限制（无 429 错误）
智能播放器检测：find_active_players 可自动发现当天处于活跃状态的视频
每个客户端独立的 .env 文件：在多个账户间实现整洁的凭据管理
Related MCP server: MCP YouTube Intelligence
Node.js ≥ 18
拥有 Analytics API 访问权限的 vTurb 账户
从 app.vturb.com/settings/analytics-api 获取的 API 令牌
Claude Code (CLI 或 VSCode 扩展)
git clone https://github.com/hiperbold/vturb-mcp.git
cd vturb-mcp
npm install
npm run build.env 文件该 MCP 使用每个客户端独立的 .env 文件，以便您可以整洁地管理多个 vTurb 账户。请以客户端名称命名文件：
# Copy the example
cp .env.example .env.nome-do-cliente
# Edit and paste your token
# .env.paula-ardanza
VTURB_API_TOKEN=your_token_here文件格式很简单 — 每行一个变量：
VTURB_API_TOKEN=eyJ...安全性： 切勿提交
.env.*文件。它们已被包含在.gitignore中。
打开 ~/.claude/mcp.json（如果不存在则创建）并添加：
{
"mcpServers": {
"vturb-mcp": {
"command": "node",
"args": ["/absolute/path/to/vturb-mcp/dist/index.js"],
"env": {
"VTURB_ENV_FILE": "/absolute/path/to/vturb-mcp/.env.nome-do-cliente"
}
}
}
}Windows 示例：
{
"mcpServers": {
"vturb-mcp": {
"command": "node",
"args": ["F:\\local-mcps\\vturb-mcp\\dist\\index.js"],
"env": {
"VTURB_ENV_FILE": "F:\\local-mcps\\vturb-mcp\\.env.paula-ardanza"
}
}
}
}MCP 服务器将在下一次会话中自动启动。您将在可用工具列表中看到它。
要切换账户，只需更新 mcp.json 中的 VTURB_ENV_FILE 以指向不同的 .env 文件，然后重启 Claude：
"VTURB_ENV_FILE": "F:\\local-mcps\\vturb-mcp\\.env.outro-cliente"工具 | 描述 |
| 列出账户中所有播放器，包含 |
| 智能工具。 列出所有播放器，检查哪些在当天有活动，并仅返回带有元数据的活跃播放器。优先使用此工具来查找正确的 |
| 返回当前的 API 配额状态：已用查询数、剩余查询数和重置时间。使用此工具监控消耗量，避免达到 120 次请求/分钟的限制。 |
| 返回当前正在观看的用户数，按域名细分。可配置时间窗口（1–720 分钟）。 |
工具 | 描述 |
| 播放器的主要分析仪表板：总观看次数、播放次数、唯一会话/设备数、互动率、点击数、转化数以及以 BRL/USD/EUR 计算的收入。 |
| 与 |
工具 | 描述 |
| 返回 |
| 与上述事件总数相同，但按天细分以进行趋势分析。 |
工具 | 描述 |
| 返回视频留存曲线：每秒有多少用户仍在观看。同时返回 |
| 返回选定周期内每天的互动率。 |
工具 | 描述 |
| 返回按视频秒数分组的 CTA 点击次数。识别视频中驱动意图最强的时刻。 |
| 按天细分的 CTA 点击总数。 |
工具 | 描述 |
| 按天分组的转化总数，包含唯一会话和设备计数。 |
工具 | 描述 |
| 按流量来源细分会话指标。支持 |
工具 | 描述 |
| 返回预计算的摘要（观看次数、播放次数、互动率、点击率和转化率）——与 vTurb 仪表板标题中显示的数据相同。 |
1. find_active_players → discover which player_id is in use today
2. get_session_stats → get the main KPIs for a date range
3. get_user_engagement → inspect the retention curve
4. get_clicks_timed → find when viewers click the CTA
5. get_conversions_by_day → track conversion trends
6. get_traffic_origin_stats → compare traffic sources客户端使用为 Pro 层级配置的令牌桶算法：
限制： 每分钟 120 次请求
填充速率： 每秒 2 个令牌
行为： 如果桶为空，请求会自动等待 — 不会抛出错误，无需重试
使用 get_quota_usage 从 vTurb 端检查实时消耗情况。
vturb-mcp/
src/
env.ts — loads .env.* file at startup (via VTURB_ENV_FILE)
client.ts — rate-limited HTTP client (token bucket, 120 req/min)
index.ts — MCP server, registers all 15 tools
tools/ — one file per tool
list-players.ts
find-active-players.ts
get-quota-usage.ts
get-session-stats.ts
get-session-stats-by-day.ts
get-events-total.ts
get-events-by-day.ts
get-user-engagement.ts
get-user-engagement-by-day.ts
get-clicks-timed.ts
get-clicks-by-day.ts
get-conversions-by-day.ts
get-live-users.ts
get-headlines-stats.ts
get-traffic-origin-stats.ts
dist/ — compiled output (run npm run build)
.env.example — template for creating client-specific env files基础 URL: https://analytics.vturb.net
认证请求头: X-Api-Token + X-Api-Version: v1
MIT
This server cannot be deployed
Analytics for MCP servers. Query your tool calls, first-call success, retries and schema cost.
Analytics for MCP servers. Find out which of your tools agents get wrong. MCPulse shows you which tools AI agents retry, which come back empty, and which they never call at all. Two lines inside your own server. It never sees your arguments or your results. getmcpulse.com
Clamp Analytics MCP server: traffic, revenue, funnels, cohorts, errors, and search, for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
