# AI Usage (npm · ai-usage-mcp)

Reports real token usage and cost from Claude Code and OpenCode data. Nothing leaves your machine.

- Trust score: 90/100 (high trust)
- Change this week: +3
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-09-21

## Components

- npm · `ai-usage-mcp`: 90/100 (this document), [markdown](https://verifymcp.io/servers/mohitbansal321-ai-usage-mcp/ai-usage-mcp.md), [page](https://verifymcp.io/servers/mohitbansal321-ai-usage-mcp/ai-usage-mcp)

## Channel facts

- Registry: `npm`
- Package: `ai-usage-mcp`
- Version: `0.9.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-09-21.

- **Supply Chain Security**: 98/100
  - No malware found by supply-chain analysis.
  - No known CVEs affecting this package version or its production dependencies.
  - No install/post-install scripts declared.
  - 31 of 97 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 100/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to MohitBansal321/ai-usage-mcp).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 2 days ago).
  - Publishes a security disclosure policy (SECURITY.md).
- **Schema Quality & AI Usability**: 77/100
  - 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).
  - AI-judged instruction clarity (excellent).
  - Context-footprint check failed: tool/resource definitions use about 3755 tokens (~312/item across 12 items; 9 tools + 3 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 60/100
  - Stability observed for 18 of 30 days with no destabilising changes; credit accrues until the full window elapses.
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 9 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 11 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

## Install

### How do I install the AI Usage MCP server?

AI Usage runs locally as an npm package, launched with npx -y ai-usage-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add mohitbansal321-ai-usage-mcp -- npx -y ai-usage-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "mohitbansal321-ai-usage-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ai-usage-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "mohitbansal321-ai-usage-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ai-usage-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add mohitbansal321-ai-usage-mcp -- npx -y ai-usage-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mohitbansal321-ai-usage-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "ai-usage-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add mohitbansal321-ai-usage-mcp --command npx --arg -y --arg ai-usage-mcp
```

### Hermes

```yaml
mcp_servers:
  mohitbansal321-ai-usage-mcp:
    command: "npx"
    args: ["-y", "ai-usage-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "mohitbansal321-ai-usage-mcp": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "ai-usage-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add mohitbansal321-ai-usage-mcp -t stdio -c npx -a -y ai-usage-mcp
```

### Other

```json
{
  "mcpServers": {
    "mohitbansal321-ai-usage-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "ai-usage-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-09-21 (score 90, +1)

No change was recorded against any check on this day. Stability & Change Management went from 57 to 60. That category is still filling its 30-day observation window: 17 days of observed history at the previous scan, 18 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-19 (score 89, +1)

No change was recorded against any check on this day. Stability & Change Management went from 50 to 53. That category is still filling its 30-day observation window: 15 days of observed history at the previous scan, 16 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-18 (score 88, 0)

- [security regression] Tool safety: pass → unverified
- [security regression] Stability: 0.47 → unverified
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified
- [functional] Package version: 0.8.0 → 0.9.0

### 2026-09-17 (score 88, 0)

- [security regression] Stability: 0.43 → unverified
- [security regression] Tool safety: pass → unverified
- [functional regression] Schema quality: 181 → 310
- [functional regression] Capabilities: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Schema quality: 100 → unverified
- [functional] Package version: 0.7.0 → 0.8.0

### 2026-09-15 (score 88, +1)

No change was recorded against any check on this day. Stability & Change Management went from 37 to 40. That category is still filling its 30-day observation window: 11 days of observed history at the previous scan, 12 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-13 (score 87, +1)

No change was recorded against any check on this day. Stability & Change Management went from 30 to 33. That category is still filling its 30-day observation window: 9 days of observed history at the previous scan, 10 at this one. The score rises as the window fills, whether or not the server changes.

### 2026-09-11 (score 86, +26)

- [security improvement] Malware scan: unverified → pass
- [security improvement] Known CVEs: unverified → pass
- [functional improvement] Dependency health: unverified → 0.85

### 2026-09-10 (score 60, −22)

- [security regression] Known CVEs: pass → unverified
- [security regression] Malware scan: pass → unverified
- [functional regression] Schema quality: 164 → 181
- [functional regression] Dependency health: 0.85 → unverified
- [functional improvement] Stability: unverified → 0.23
- [functional] Package version: 0.5.1 → 0.7.0
- [functional] Package version: 0.5.1 → 0.6.0

## MCP tools (9)

### `usage_summary` (~438 tokens)

Usage summary

Total token usage and cost for a period, split by client (Claude Code, OpenCode). Tokens are broken out into input / output / cache-read / cache-write / reasoning, because cache tokens typically dwarf input and a single blended total is misleading. Reported cost (from OpenCode) and estimated cost (computed for Claude Code, which records none) are always listed separately and must not be summed. Also reports the cache hit rate and reads-per-write, which are what say whether the cache is paying for itself -- the raw cache counts alone cannot.

Input parameters:

- `client`: Restrict to any of these clients. A single client id is also accepted.
- `compare` (string): Also report the window of equal length immediately before this one, with the delta. Requires a period of fixed length -- days, today, or since AND until together. An open-ended period (since alone, u…
- `days` (integer): Look back this many days, counted from local midnight. Omit for all time.
- `includeSubagents` (boolean): Include subagent/sidechain turns. Defaults to true, because they are real spend. Set false to see only main-thread turns.
- `models` (array): Restrict to any of these model ids, exactly as the client recorded them. Use model_usage to see the ids present.
- `projectPath` (string): Deprecated spelling of projectPaths, for one project. Still honoured.
- `projectPaths` (array): Restrict to any of these projects, given as the absolute working directories the turns ran in. Each must match exactly; use project_usage to see the available paths. A value matching no record anywhe…
- `since` (string): ISO 8601 start of the period (inclusive).
- `today` (boolean): Restrict to today, in local time.
- `until` (string): ISO 8601 end of the period (exclusive).

### `session_usage` (~90 tokens)

Session usage

Usage for one session: client, model(s), duration, token breakdown and cost. Accepts a full session id or an unambiguous fragment of one. Subagent turns are reported separately from main-thread turns.

Input parameters:

- `includeSubagents` (boolean): Include subagent turns in the totals. Defaults to true.
- `sessionId` (string, required): Session id, or an unambiguous part of one.

### `model_usage` (~379 tokens)

Usage by model

Per-model token usage and cost, highest token count first. Use this to answer "which model consumed the most tokens". Cost is labelled reported vs estimated per model.

Input parameters:

- `client`: Restrict to any of these clients. A single client id is also accepted.
- `days` (integer): Look back this many days, counted from local midnight. Omit for all time.
- `includeSubagents` (boolean): Include subagent/sidechain turns. Defaults to true, because they are real spend. Set false to see only main-thread turns.
- `limit` (integer): Rows to return.
- `models` (array): Restrict to any of these model ids, exactly as the client recorded them. Use model_usage to see the ids present.
- `offset` (integer): Rows to skip, for paging. Use the `nextOffset` from the previous result.
- `projectPath` (string): Deprecated spelling of projectPaths, for one project. Still honoured.
- `projectPaths` (array): Restrict to any of these projects, given as the absolute working directories the turns ran in. Each must match exactly; use project_usage to see the available paths. A value matching no record anywhe…
- `since` (string): ISO 8601 start of the period (inclusive).
- `sort` (string): Row ordering, descending. There is deliberately no plain "cost": reported and estimated cost are separate figures that are never summed, so ordering by one sorts every row priced on the other basis a…
- `today` (boolean): Restrict to today, in local time.
- `until` (string): ISO 8601 end of the period (exclusive).

### `client_usage` (~386 tokens)

Usage by client

Token usage and cost per coding agent (Claude Code vs OpenCode). Note that the two cost figures are not comparable as a single number: OpenCode reports actual charged cost, while the Claude Code figure is an API-equivalent estimate (a Pro/Max subscription has $0 marginal cost per request).

Input parameters:

- `days` (integer): Look back this many days, counted from local midnight. Omit for all time.
- `includeSubagents` (boolean): Include subagent/sidechain turns. Defaults to true, because they are real spend. Set false to see only main-thread turns.
- `limit` (integer): Rows to return.
- `models` (array): Restrict to any of these model ids, exactly as the client recorded them. Use model_usage to see the ids present.
- `offset` (integer): Rows to skip, for paging. Use the `nextOffset` from the previous result.
- `projectPath` (string): Deprecated spelling of projectPaths, for one project. Still honoured.
- `projectPaths` (array): Restrict to any of these projects, given as the absolute working directories the turns ran in. Each must match exactly; use project_usage to see the available paths. A value matching no record anywhe…
- `since` (string): ISO 8601 start of the period (inclusive).
- `sort` (string): Row ordering, descending. There is deliberately no plain "cost": reported and estimated cost are separate figures that are never summed, so ordering by one sorts every row priced on the other basis a…
- `today` (boolean): Restrict to today, in local time.
- `until` (string): ISO 8601 end of the period (exclusive).

### `project_usage` (~409 tokens)

Usage by project

Per-project token usage and cost, highest token count first. A project is the working directory a turn ran in. Use this to answer "which repository is my spend going to". Turns whose project could not be resolved are grouped as (unknown) rather than dropped, and cost is labelled reported vs estimated per project.

Input parameters:

- `client`: Restrict to any of these clients. A single client id is also accepted.
- `days` (integer): Look back this many days, counted from local midnight. Omit for all time.
- `includeSubagents` (boolean): Include subagent/sidechain turns. Defaults to true, because they are real spend. Set false to see only main-thread turns.
- `limit` (integer): Rows to return.
- `models` (array): Restrict to any of these model ids, exactly as the client recorded them. Use model_usage to see the ids present.
- `offset` (integer): Rows to skip, for paging. Use the `nextOffset` from the previous result.
- `projectPath` (string): Deprecated spelling of projectPaths, for one project. Still honoured.
- `projectPaths` (array): Restrict to any of these projects, given as the absolute working directories the turns ran in. Each must match exactly; use project_usage to see the available paths. A value matching no record anywhe…
- `since` (string): ISO 8601 start of the period (inclusive).
- `sort` (string): Row ordering, descending. There is deliberately no plain "cost": reported and estimated cost are separate figures that are never summed, so ordering by one sorts every row priced on the other basis a…
- `today` (boolean): Restrict to today, in local time.
- `until` (string): ISO 8601 end of the period (exclusive).

### `daily_usage` (~421 tokens)

Usage by day

Token usage and cost bucketed on the time axis, newest first. Use this for "how much did I use yesterday", for a trend over a period, or -- with grain "hour-of-day" -- for "when during the day do I burn tokens". Buckets with NO activity are included and flagged `zeroFilled`, because omitting them hides the gaps and makes an ordinary bucket look like a spike beside one weeks earlier. All buckets are local time, so they agree with the period filter rather than drifting by a timezone offset. Cost is labelled reported vs estimated per bucket.

Input parameters:

- `client`: Restrict to any of these clients. A single client id is also accepted.
- `days` (integer): Look back this many days, counted from local midnight. Omit for all time.
- `grain` (string): Time bucket (default day). "hour" is a finer timeline; "hour-of-day" collapses every day onto one 24-slot local clock, which is what answers "when during the day do I burn tokens". All are local time…
- `includeSubagents` (boolean): Include subagent/sidechain turns. Defaults to true, because they are real spend. Set false to see only main-thread turns.
- `models` (array): Restrict to any of these model ids, exactly as the client recorded them. Use model_usage to see the ids present.
- `projectPath` (string): Deprecated spelling of projectPaths, for one project. Still honoured.
- `projectPaths` (array): Restrict to any of these projects, given as the absolute working directories the turns ran in. Each must match exactly; use project_usage to see the available paths. A value matching no record anywhe…
- `since` (string): ISO 8601 start of the period (inclusive).
- `today` (boolean): Restrict to today, in local time.
- `until` (string): ISO 8601 end of the period (exclusive).

### `usage_breakdown` (~519 tokens)

Usage broken down by two dimensions

Token usage and cost cut by two or more dimensions at once -- project x day, model x day, client x day -- as one tidy row set. Use this for "which of my projects is getting more expensive", which the single-axis tools cannot answer: project_usage gives a total with no trend, and daily_usage narrowed to one project gives one series, so answering it otherwise means enumerating projects and issuing one call each. Combinations with no activity are absent rather than returned as zero rows. Cost stays labelled reported vs estimated per row and the two are never summed.

Input parameters:

- `axes` (array, required): Dimensions to cross, in output order: client, model, provider, project, session, day, hour, hour-of-day. At most 3, and each at most once. The time axes bucket in local time, identically to daily_usa…
- `client`: Restrict to any of these clients. A single client id is also accepted.
- `days` (integer): Look back this many days, counted from local midnight. Omit for all time.
- `includeSubagents` (boolean): Include subagent/sidechain turns. Defaults to true, because they are real spend. Set false to see only main-thread turns.
- `limit` (integer): Rows to return.
- `models` (array): Restrict to any of these model ids, exactly as the client recorded them. Use model_usage to see the ids present.
- `offset` (integer): Rows to skip, for paging. Use the `nextOffset` from the previous result.
- `projectPath` (string): Deprecated spelling of projectPaths, for one project. Still honoured.
- `projectPaths` (array): Restrict to any of these projects, given as the absolute working directories the turns ran in. Each must match exactly; use project_usage to see the available paths. A value matching no record anywhe…
- `since` (string): ISO 8601 start of the period (inclusive).
- `sort` (string): Row ordering, descending. There is deliberately no plain "cost": reported and estimated cost are separate figures that are never summed, so ordering by one sorts every row priced on the other basis a…
- `today` (boolean): Restrict to today, in local time.
- `until` (string): ISO 8601 end of the period (exclusive).

### `counterfactual_cost` (~528 tokens)

Cost on another model

What the tokens from a period would have cost at another model’s list rates, alongside what they actually cost. Use this for "would Sonnet have been cheaper than Opus for this". It re-prices the exact token counts that were recorded, grouped by client, model and speed so the fast-mode premium and the two different reasoning-token conventions are handled correctly. Also reports what the same tokens would have cost with NO prompt caching at all, per model -- which is the figure that says whether caching is paying for itself. IMPORTANT: the model scenarios are a counterfactual, not a saving — the same task on a different model generally takes a different number of turns with a different context on each, and nothing on disk can say what that would have been. Report it as such, keep every scenario labelled an estimate, and never subtract a scenario from the reported cost to claim a number.

Input parameters:

- `client`: Restrict to any of these clients. A single client id is also accepted.
- `days` (integer): Look back this many days, counted from local midnight. Omit for all time.
- `filterModels` (array): Restrict which turns are included, by model id -- the same scope filter other tools spell `models`. Named apart here because `models` already meant "price against these" on this tool. Use both togeth…
- `includeSubagents` (boolean): Include subagent/sidechain turns. Defaults to true, because they are real spend. Set false to see only main-thread turns.
- `models` (array): Deprecated spelling of targetModels. Still honoured.
- `projectPath` (string): Deprecated spelling of projectPaths, for one project. Still honoured.
- `projectPaths` (array): Restrict to any of these projects, given as the absolute working directories the turns ran in. Each must match exactly; use project_usage to see the available paths. A value matching no record anywhe…
- `since` (string): ISO 8601 start of the period (inclusive).
- `targetModels` (array): Models to price the selected tokens AGAINST. Not a filter on which turns are included -- that is `filterModels`. Omit to compare every model the pricing table knows. A model with no price is omitted…
- `today` (boolean): Restrict to today, in local time.
- `until` (string): ISO 8601 end of the period (exclusive).

### `recent_sessions` (~377 tokens)

Recent sessions

Most recently active sessions with project path, client, model(s), duration, token breakdown and cost. Use the returned session id with session_usage for detail.

Input parameters:

- `client`: Restrict to any of these clients. A single client id is also accepted.
- `days` (integer): Look back this many days, counted from local midnight. Omit for all time.
- `includeSubagents` (boolean): Include subagent/sidechain turns. Defaults to true, because they are real spend. Set false to see only main-thread turns.
- `limit` (integer): Rows to return.
- `models` (array): Restrict to any of these model ids, exactly as the client recorded them. Use model_usage to see the ids present.
- `offset` (integer): Rows to skip, for paging. Use the `nextOffset` from the previous result.
- `projectPath` (string): Deprecated spelling of projectPaths, for one project. Still honoured.
- `projectPaths` (array): Restrict to any of these projects, given as the absolute working directories the turns ran in. Each must match exactly; use project_usage to see the available paths. A value matching no record anywhe…
- `since` (string): ISO 8601 start of the period (inclusive).
- `sort` (string): Row ordering, descending. There is deliberately no plain "cost": reported and estimated cost are separate figures that are never summed, so ordering by one sorts every row priced on the other basis a…
- `today` (boolean): Restrict to today, in local time.
- `until` (string): ISO 8601 end of the period (exclusive).

## Diagnostics

Captured diagnostic sections: Provenance, Dependencies. The full working is on the page: https://verifymcp.io/servers/mohitbansal321-ai-usage-mcp/ai-usage-mcp#diagnostics

## Score history

- 2026-09-21: 90
- 2026-09-20: 89
- 2026-09-19: 89
- 2026-09-18: 88
- 2026-09-17: 88
- 2026-09-16: 88
- 2026-09-15: 88
- 2026-09-14: 87
- 2026-09-13: 87
- 2026-09-12: 86
- 2026-09-11: 86
- 2026-09-10: 60
- 2026-09-09: 82
- 2026-09-08: 82
- 2026-09-07: 82
- 2026-09-06: 82
- 2026-09-05: 82
- 2026-09-04: 82
- 2026-09-03: 72

## Common questions

### What is the AI Usage MCP server?

AI Usage is an MCP server listed in the public MCP registry as io.github.MohitBansal321/ai-usage-mcp. Reports real token usage and cost from Claude Code and OpenCode data. Nothing leaves your machine. This page covers its npm package (ai-usage-mcp).

### Is the AI Usage MCP server safe to use?

AI Usage scores 90 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 September 2026. It declares no install or post-install scripts. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the AI Usage MCP server expose?

AI Usage exposes 9 tools: usage_summary, session_usage, model_usage, client_usage, project_usage, and 4 more. Their descriptions and schemas cost roughly 3,547 tokens of context every time the server is loaded.

### Is the AI Usage MCP server still maintained?

AI Usage is still listed as active in the MCP registry. We last reached this channel on 21 September 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the AI Usage MCP server under?

AI Usage declares the MIT licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- npm package: https://www.npmjs.com/package/ai-usage-mcp
- Socket report: https://socket.dev/npm/package/ai-usage-mcp
- Repository: https://github.com/MohitBansal321/ai-usage-mcp
- Changelog RSS feed: https://verifymcp.io/servers/mohitbansal321-ai-usage-mcp/ai-usage-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/mohitbansal321-ai-usage-mcp/ai-usage-mcp.json
- HTML version of this page: https://verifymcp.io/servers/mohitbansal321-ai-usage-mcp/ai-usage-mcp