Submit AI coding usage to a leaderboard and track developer statistics for tools like Claude Code and Codex.
Also known as sculptdotfun/viberank, viberank-mcp
- Stars
- 121
- Tools
- 5
- Downloads, 30 days
- —
- Latest version
- 1.2.0
- Last commit
- Oct 26, 2026
- License
- MIT
What is viberank MCP?
viberank is an MCP server. Submit AI coding usage to a leaderboard and track developer statistics for tools like Claude Code and Codex. It exposes 5 tools, such as get_usage, submit_to_viberank, get_leaderboard.
Summary generated from the project's README
About viberank MCP server
viberank allows developers to track and share their AI coding usage statistics through a public leaderboard. By connecting this MCP server to clients like Claude Desktop or Claude Code, you can monitor how much you spend on tools such as Codex, Gemini CLI, and OpenCode. The server uses ccusage to calculate local metrics including token counts and API-equivalent costs.
To use the server, you can run it via npx as a stdio server. For automatic verification and account filing, you should provide a VIBERANK_TOKEN starting with vbr_. If you choose not to use a token, you must provide a GitHub username to identify your public profile. The server provides tools to fetch your personal usage, view the global leaderboard with specific tool filters, and access site-wide statistics regarding developer adoption and monthly spending trends.
What you can do with it
- 1Submit coding usage to a leaderboardUpload your local AI tool usage data to your public profile on viberank.
- 2View global developer rankingsCheck the top users for a specific tool like Codex or Gemini.
- 3Analyze personal AI spendingGet a summary of your tokens and costs across different coding agents.
Written from the project's README. Every use case is checked against a quote from it.
How to install viberank MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall viberank MCP in Claude Code
$ claude mcp add --env 'VIBERANK_TOKEN=<YOUR_VIBERANK_TOKEN>' viberank -- npx -y viberank-mcpInstall viberank MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"viberank": {
"command": "npx",
"args": [
"-y",
"viberank-mcp"
],
"env": {
"VIBERANK_TOKEN": "<YOUR_VIBERANK_TOKEN>"
}
}
}
}Install viberank MCP in VS Code
.vscode/mcp.json
{
"servers": {
"viberank": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"viberank-mcp"
],
"env": {
"VIBERANK_TOKEN": "<YOUR_VIBERANK_TOKEN>"
}
}
}
}Install viberank MCP in VS Code CLI
$ code --add-mcp '{"name":"viberank","type":"stdio","command":"npx","args":["-y","viberank-mcp"],"env":{"VIBERANK_TOKEN":"<YOUR_VIBERANK_TOKEN>"}}'Install viberank MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"viberank": {
"command": "npx",
"args": [
"-y",
"viberank-mcp"
],
"env": {
"VIBERANK_TOKEN": "<YOUR_VIBERANK_TOKEN>"
}
}
}
}Install viberank MCP in Codex
$ codex mcp add viberank --env 'VIBERANK_TOKEN=<YOUR_VIBERANK_TOKEN>' -- npx -y viberank-mcpInstall viberank MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.viberank] command = "npx" args = ["-y", "viberank-mcp"] [mcp_servers.viberank.env] VIBERANK_TOKEN = "<YOUR_VIBERANK_TOKEN>"
Install viberank MCP in Gemini CLI
$ gemini mcp add -s user -e 'VIBERANK_TOKEN=<YOUR_VIBERANK_TOKEN>' viberank npx -- -y viberank-mcpInstall viberank MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"viberank": {
"command": "npx",
"args": [
"-y",
"viberank-mcp"
],
"env": {
"VIBERANK_TOKEN": "<YOUR_VIBERANK_TOKEN>"
}
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for viberank-mcp 1.2.0 in an isolated container with no network and no keys. It answered and listed 5 tools.
viberank MCP tools 5
Read from the server with tools/listget_usageRead the user's local AI coding usage (Claude Code, Codex, Gemini CLI, OpenCode and the other tools ccusage supports) by running ccusage@20 on this machine. Returns a summary: API-equivalent cost in USD, tokens, days tracked, date range and cost per tool. Sends nothing anywhere. Can take a minute on a long history; results are cached for 5 minutes.
submit_to_viberankUpload the user's local usage to the public viberank.app leaderboard. Call it only when the user asked to submit. With a VIBERANK_TOKEN configured, the submission is verified and filed under the token's account, so leave github_username out. Without a token, github_username is required and must be the user's own GitHub handle, confirmed with them, because it becomes a public profile. Called without one, it uploads nothing and suggests a handle to confirm with the user before calling again. On success it returns rank, tier and a README badge you can offer to add.
get_leaderboardThe current viberank leaderboard, ranked by API-equivalent cost. Each entry has rank, username, totalCost (USD), totalTokens, tools, verified, underReview and profileUrl. Pass tool to rank only the users of one tool; get_stats lists the tool slugs.
get_profileOne developer's viberank profile: global rank, total cost and tokens, days tracked, tools and whether it is verified. Profiles are keyed by GitHub username. Returns found: false when there's no such profile.
get_statsSite-wide viberank statistics: developer and submission counts, total tokens and API-equivalent cost, monthly spend per developer (median and percentiles), tool and model adoption, the monthly trend and tier counts, with methodology, caveats and a citation line. Use it to compare one developer's spend with everyone else's.
Configuration
VIBERANK_TOKENSecretOptional API token from https://www.viberank.app/settings/tokens. Signs submissions so they are verified and filed under your account.
Automated checks
Ran Nov 16, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablesculptdotfun/viberank is public and reachablegithub.com/sculptdotfun/viberank ↗Pass
- Package names this repository as its sourceviberank-mcp names sculptdotfun/viberank as sourcenpmjs.com/package/viberank-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-26github.com/sculptdotfun/viberank ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from viberank-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubviberank MCP server
Submit your AI coding usage (Claude Code, Codex, Gemini CLI, OpenCode and every other tool ccusage reads) to viberank, and read the leaderboard, from any MCP client.
Install
Claude Code
claude mcp add --scope user viberank -- npx -y viberank-mcp
To have submissions verified and filed under your account automatically, add an API token. Mint one at viberank.app/settings/tokens (sign in with GitHub, then Create token); it starts with vbr_:
claude mcp add --scope user viberank --env VIBERANK_TOKEN=vbr_… -- npx -y viberank-mcp
On native Windows (not WSL), npx has to go through cmd /c:
claude mcp add --scope user viberank -- cmd /c npx -y viberank-mcp
--scope user makes the server available in every project. Check it with claude mcp list.
Claude Desktop
Add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude Desktop. Leave out the env block if you don't have a token.
{
"mcpServers": {
"viberank": {
"command": "npx",
"args": ["-y", "viberank-mcp"],
"env": {
"VIBERANK_TOKEN": "vbr_…"
}
}
}
}
On Windows, use cmd /c:
{
"mcpServers": {
"viberank": {
"command": "cmd",
"args": ["/c", "npx", "-y", "viberank-mcp"],
"env": {
"VIBERANK_TOKEN": "vbr_…"
}
}
}
}
Other MCP clients
Run npx -y viberank-mcp as a stdio server. Node.js 18 or newer.
Which account a submission goes to
- With a token (
VIBERANK_TOKEN, or the onenpx viberank-cli loginsaved in~/.viberank/config.json): the server files the submission under the token's owner and marks it verified. The MCP server asks viberank who that is before uploading, and the result names that account. No username is needed. - Without a token:
github_usernameis required, and it should be your own GitHub handle, because it becomes a public profile. If the agent calls without one, nothing is uploaded. The MCP server suggests a handle instead (the one this machine submitted under before, or the repository's owner when GitHub confirms that's a personal account, never an organization) and the agent asks you to confirm it before calling again. Once a profile is verified, unsigned submissions to it are refused, so nobody else can write to yours.
Tools
get_usage
Runs ccusage@20 daily --json --by-agent locally and returns a summary: API-equivalent cost, tokens, days tracked, date range and cost per tool. Sends nothing. Cached for 5 minutes.
force_refresh(boolean, optional): re-run ccusage instead of using the cache.
submit_to_viberank
Uploads your usage to the leaderboard. On success it returns the account it was filed under, your profile URL, your standing (rank, top percentage, tier, and README badge markdown), and next steps the agent can offer: adding the badge to your README, and turning on daily autosubmit with npx viberank-cli login and npx viberank-cli autosubmit.
github_username(string): your GitHub username. Required without a token, not needed with one.
get_leaderboard
The current leaderboard: rank, username, cost, tokens, tools and verified status for each entry.
limit(integer, optional): 1 to 50, default 10.tool(string, optional): rank only users of one tool, such asclaude,codex,gemini,opencodeorcopilot.
get_profile
One developer's profile: rank, cost, tokens, days tracked, tools and verified status. Says found: false when there's no profile for that username.
username(string, required): the GitHub username.
get_stats
Site-wide numbers from /api/stats: developer count, total spend and tokens, monthly spend percentiles, tool and model adoption, the monthly trend and tiers, with methodology and caveats.
Example prompts
- "What's my AI coding usage?"
- "Submit my usage to viberank."
- "Show the top 20 on viberank for Codex."
- "Look up octocat on viberank."
- "How does my monthly spend compare with other developers?"
What is sent, and where
Only submit_to_viberank sends your usage, and only to https://www.viberank.app/api/submit. Along with the ccusage report it sends:
Authorization: Bearer <token>when you have a token, otherwiseX-GitHub-User: <username>.X-Machine-Id: the anonymous random ID in~/.viberank/machine-id, shared with the CLI and created on first use, so usage from your laptop and desktop adds up instead of overwriting.X-Viberank-Client: mcp/<version>.
The read tools fetch public data from viberank.app. Without a token, submit_to_viberank also asks the GitHub API whether a suggested handle is a personal account; only the handle is sent.
Troubleshooting
- "VIBERANK_TOKEN is set but is not a viberank token": the variable holds something other than
vbr_plus 43 characters, often thevbr_…placeholder from these docs. Paste the real token or remove the variable. - "was rejected by viberank": the token was revoked. Mint a new one at viberank.app/settings/tokens.
- "a GitHub username is required": there's no token, so tell the agent your GitHub username, or add a token.
- "No usage found": ccusage found no logs on this machine. Use Claude Code, Codex or another supported tool first.
- "Could not run ccusage@20": check that
npx --versionworks and that the machine is online; the first run downloads ccusage.
Development
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)
The smoke test never calls submit_to_viberank.
The package is listed in the MCP registry as io.github.sculptdotfun/viberank (mcpName in package.json, metadata in server.json). Keep the version fields in server.json in step with package.json.
Links
- viberank
- Source
- Issues
- viberank-cli, for submitting from a terminal and daily autosubmit
License
MIT
viberank MCP questions
How do I add viberank MCP to Claude Code?
Run claude mcp add --env 'VIBERANK_TOKEN=<YOUR_VIBERANK_TOKEN>' viberank -- npx -y viberank-mcp in your terminal. Add --scope user to make it available in every project.
How do I add viberank MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does viberank MCP provide?
It exposes 5 tools, including get_usage, submit_to_viberank, get_leaderboard, get_profile, get_stats.
How do I submit my usage to viberank?
You can use the submit_to_viberank tool. If you have an API token, it files under your account automatically; otherwise, you must provide your GitHub username.
What information is sent when I submit my usage?
The server sends a ccusage report along with your authorization token or GitHub username, an anonymous machine ID, and the client version.