viberank

viberank MCP 服务

将你的 AI 编码用量（Claude Code、Codex、Gemini CLI、OpenCode 以及 ccusage 可读取的所有其他工具）提交到 viberank，并通过任意 MCP 客户端查看排行榜。

安装

Claude Code

claude mcp add --scope user viberank -- npx -y viberank-mcp

要自动验证提交并将其归入你的账户，请添加 API 令牌。在 viberank.app/settings/tokens 创建令牌（使用 GitHub 登录，然后点击 Create token）；令牌以 vbr_ 开头：

claude mcp add --scope user viberank --env VIBERANK_TOKEN=vbr_… -- npx -y viberank-mcp

在原生 Windows（非 WSL）上，npx 必须通过 cmd /c 运行：

claude mcp add --scope user viberank -- cmd /c npx -y viberank-mcp

--scope user 会让所有项目都可以使用该服务。使用 claude mcp list 检查。

Claude Desktop

将以下内容添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\Claude\），然后重启 Claude Desktop。如果没有令牌，请省略 env 块。

{
  "mcpServers": {
    "viberank": {
      "command": "npx",
      "args": ["-y", "viberank-mcp"],
      "env": {
        "VIBERANK_TOKEN": "vbr_…"
      }
    }
  }
}

在 Windows 上，使用 cmd /c：

{
  "mcpServers": {
    "viberank": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "viberank-mcp"],
      "env": {
        "VIBERANK_TOKEN": "vbr_…"
      }
    }
  }
}

其他 MCP 客户端

将 npx -y viberank-mcp 作为 stdio 服务运行。需要 Node.js 18 或更高版本。

提交归属哪个账户

• 有令牌时（VIBERANK_TOKEN，或由 npx viberank-cli login 保存到 ~/.viberank/config.json 的令牌）：服务会将提交归入令牌所有者名下，并标记为已验证。MCP 服务会在上传前询问 viberank 该令牌属于谁，结果会显示该账户。无需提供用户名。
• 没有令牌时：必须提供 github_username，且应为你自己的 GitHub 用户名，因为它会成为公开个人资料。如果 Agent 未提供用户名就调用，不会上传任何内容。MCP 服务会改为建议一个用户名（此机器之前提交时使用的用户名；或者在 GitHub 确认仓库所有者是个人账户而非组织时，建议该所有者的用户名），并由 Agent 在再次调用前请你确认。个人资料通过验证后，将拒绝向其提交未经签名的数据，因此其他人无法向你的个人资料提交数据。

工具

get_usage

在本地运行 ccusage@20 daily --json --by-agent，并返回摘要：API 等效成本、令牌数、统计天数、日期范围以及各工具的成本。不会发送任何数据。缓存 5 分钟。

• force_refresh（布尔值，可选）：重新运行 ccusage，而不是使用缓存。

submit_to_viberank

将你的用量上传到排行榜。成功后会返回提交归属的账户、个人资料 URL、你的排名情况（排名、百分位、等级和 README 徽章 Markdown），以及 Agent 可以提供的后续操作：将徽章添加到 README，并使用 npx viberank-cli login 和 npx viberank-cli autosubmit 开启每日自动提交。

• github_username（字符串）：你的 GitHub 用户名。没有令牌时必填，有令牌时无需提供。

get_leaderboard

当前排行榜：每条记录的排名、用户名、成本、令牌数、工具和验证状态。

• limit（整数，可选）：1 到 50，默认值为 10。
• tool（字符串，可选）：仅按一种工具筛选排名用户，例如 claude、codex、gemini、opencode 或 copilot。

get_profile

一位开发者的个人资料：排名、成本、令牌数、统计天数、工具和验证状态。如果该用户名没有个人资料，则返回 found: false。

• username（字符串，必填）：GitHub 用户名。

get_stats

来自 /api/stats 的全站数据：开发者数量、总支出和令牌数、月度支出百分位数、工具和模型采用情况、月度趋势和等级，以及相关方法说明与注意事项。

示例提示词

• “我的 AI 编码用量是多少？”
• “将我的用量提交到 viberank。”
• “显示 viberank 上 Codex 的前 20 名。”
• “查询 octocat 在 viberank 上的资料。”
• “我的月度支出与其他开发者相比如何？”

发送的内容和发送位置

只有 submit_to_viberank 会发送你的使用情况，且只发送到 https://www.viberank.app/api/submit。除 ccusage 报告外，它还会发送：

• Authorization: Bearer <token>（如果你有令牌），否则发送 X-GitHub-User: <username>。
• X-Machine-Id：~/.viberank/machine-id 中的匿名随机 ID，与 CLI 共用，并在首次使用时创建，这样你的笔记本电脑和台式机上的使用情况会累加，而不是互相覆盖。
• X-Viberank-Client: mcp/<version>。

读取工具会从 viberank.app 获取公开数据。没有令牌时，submit_to_viberank 还会查询 GitHub API，确认建议的用户名是否为个人账号；只会发送用户名。

故障排除

• “VIBERANK_TOKEN 已设置，但不是 viberank 令牌”：变量中包含的内容不是由 vbr_ 加 43 个字符组成的令牌，通常是这些文档中的 vbr_… 占位符。粘贴真实令牌或移除该变量。
• “被 viberank 拒绝”：令牌已撤销。前往 viberank.app/settings/tokens 创建新令牌。
• “需要 GitHub 用户名”：你没有令牌，因此请告知 Agent 你的 GitHub 用户名，或添加令牌。
• “未找到使用记录”：ccusage 在这台机器上没有找到日志。请先使用 Claude Code、Codex 或其他受支持的工具。
• “无法运行 ccusage@20”：检查 npx --version 是否正常运行，以及机器是否联网；首次运行时会下载 ccusage。

开发

npm install
npm run build    # tsc into dist/
npm test         # unit tests, no network
npm run smoke    # starts dist/index.js over stdio and calls the read tools against viberank.app
npm run smoke -- --usage   # also runs get_usage (ccusage, local only)

冒烟测试不会调用 submit_to_viberank。

该软件包已在 MCP registry 中列出，名称为 io.github.sculptdotfun/viberank（package.json 中的 mcpName，元数据位于 server.json）。确保 server.json 中的 version 字段与 package.json 保持一致。

链接

• viberank
• 源代码
• 问题反馈
• viberank-cli，用于从终端提交和每日自动提交

许可证

MIT