Analyzes local Claude Code transcripts to identify used, unused, or failing MCP servers and provides cleanup recommendations.
Also known as Rixtayz/mcp-usage, @rixtay/mcp-usage
- Stars
- 0
- Tools
- 4
- Downloads, 30 days
- —
- Latest version
- 0.1.1
- Last commit
- Oct 14, 2026
- License
- MIT
What is usage MCP?
usage analyzes local Claude Code transcripts to identify used, unused, or failing MCP servers and provides cleanup recommendations. It exposes 4 tools, such as usage_summary, unused_servers, server_details.
Summary generated from the project's README
About usage MCP server
Cleaning up unused or broken MCP servers from your local environment is what mcp-usage enables for developers using Claude Code. By analyzing local transcripts, this tool identifies which servers are actively being used, which remain idle, which fail to connect, and which are stuck waiting for authorization. It provides a clear way to manage your local toolset without needing any API keys, accounts, or manual configuration.
Users can interact with the server through four read-only tools: usage_summary, unused_servers, server_details, and recommendations. The recommendations tool provides a prioritized list of actions, such as disconnecting idle servers or investigating those with high error rates. Because it operates locally and streams transcripts line by line, it maintains privacy by never exposing actual conversation prompts, responses, or file paths. It is designed to run via npx or as a connected MCP server for clients like Claude Desktop.
What you can do with it
- 1Identify servers to disconnectAsk the assistant to find which MCP servers are no longer needed based on recent session history.
- 2Troubleshoot flaky toolsDetermine if a specific server is experiencing a high frequency of connection or execution errors.
- 3Audit authorization delaysFind out which connected servers have been pending authorization for an extended period.
- 4Analyze tool performanceGet a detailed breakdown of tool calls, error rates, and estimated token usage for a specific server.
Written from the project's README. Every use case is checked against a quote from it.
How to install usage MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall usage MCP in Claude Code
$ claude mcp add mcp-usage -- npx -y @rixtay/mcp-usage serveInstall usage MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-usage": {
"command": "npx",
"args": [
"-y",
"@rixtay/mcp-usage",
"serve"
]
}
}
}Install usage MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-usage": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@rixtay/mcp-usage",
"serve"
]
}
}
}Install usage MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-usage","type":"stdio","command":"npx","args":["-y","@rixtay/mcp-usage","serve"]}'Install usage MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-usage": {
"command": "npx",
"args": [
"-y",
"@rixtay/mcp-usage",
"serve"
]
}
}
}Install usage MCP in Codex
$ codex mcp add mcp-usage -- npx -y @rixtay/mcp-usage serveInstall usage MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-usage] command = "npx" args = ["-y", "@rixtay/mcp-usage", "serve"]
Install usage MCP in Gemini CLI
$ gemini mcp add -s user mcp-usage npx -- -y @rixtay/mcp-usage serveInstall usage MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-usage": {
"command": "npx",
"args": [
"-y",
"@rixtay/mcp-usage",
"serve"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for @rixtay/mcp-usage 0.1.1 in an isolated container with no network and no keys. It answered and listed 4 tools.
usage MCP tools 4
Read from the server with tools/listusage_summaryRead-onlyPer-server usage of every MCP server seen in recent Claude Code sessions: status (used / unused / failed / needs-auth), tools available, sessions, calls, error rate, estimated result tokens, last use. Reads local Claude Code transcripts only. Returns server names, tool names, counts and timestamps - never conversation content.
unused_serversRead-onlyMCP servers that were connected but never called, failed to connect, or are waiting for authorization. Reads local Claude Code transcripts only. Returns server names, tool names, counts and timestamps - never conversation content.
server_detailsRead-onlyFull stats for one MCP server, including per-tool calls, errors and result size. Reads local Claude Code transcripts only. Returns server names, tool names, counts and timestamps - never conversation content.
recommendationsRead-onlyPrioritized actions: disconnect unused servers, fix or remove failing ones, authorize or remove pending ones, investigate high error rates, watch heavy results. Reads local Claude Code transcripts only. Returns server names, tool names, counts and timestamps - never conversation content.
Automated checks
Ran Nov 14, 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 reachablerixtayz/mcp-usage is public and reachablegithub.com/rixtayz/mcp-usage ↗Pass
- Package names this repository as its source@rixtay/mcp-usage names rixtayz/mcp-usage as sourcenpmjs.com/package/@rixtay/mcp-usage ↗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-14github.com/rixtayz/mcp-usage ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @rixtay/mcp-usagePass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model4 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 GitHubmcp-usage
A small, focused MCP server and CLI that reads your local Claude Code transcripts and tells you, for every MCP server you have connected, whether it is actually used, sits idle in every session, fails to connect, or has been waiting for authorization for weeks — and what to disconnect.
Built for one job: answer "which of my MCP servers should I keep?" — locally, read-only, without ever exposing a word of your conversations.
Tools
Four tools, all read-only:
| Tool | What it does |
|---|---|
usage_summary |
One row per server: status, tools exposed, sessions, calls, error rate, estimated result tokens, last use |
unused_servers |
Servers that were connected but never called, failed to connect, or are waiting for authorization |
server_details |
One server in full, with per-tool calls, errors and result size (accepts the id or the label, case-insensitive) |
recommendations |
A prioritized action list: disconnect, fix or remove, authorize or remove, investigate errors, heavy results |
Design choices:
- Exact, not guessed. Claude Code already records, in every session, which MCP tools were available and which servers failed or needed auth. "Available but never used" is a set difference over your own logs, not a heuristic.
- Private by construction. No network code at all. The output holds server names, tool names, counts, byte totals and timestamps — never prompts, responses, tool inputs, tool outputs, file paths or error messages. The test fixtures plant
SECRET_*markers everywhere private content lives in a real transcript, and the tests assert none of them reach the library, the CLI or the MCP output. - Fast on big histories. Transcripts are streamed line by line and lines that cannot matter are skipped before
JSON.parse: ~360 MB of history (including a 90 MB session) scans in about 3 seconds. - Hygiene, not billing. Cost analyzers (ccusage, agent-cost-mcp, …) tell you how many tokens and dollars you spent. This tells you which servers earn their place.
- Every tool ships a strict input schema and MCP annotations (
readOnlyHint,idempotentHint) so hosts can auto-approve them.
Requirements
- Node.js 22 or newer.
- Claude Code (CLI, desktop app or IDE extension) with some session history on this machine. Nothing else: no account, no API key, no configuration.
1. Run the report
No install needed, npx fetches the package from npm (@rixtay/mcp-usage, the installed command is mcp-usage):
npx -y @rixtay/mcp-usage
Or from a clone:
git clone https://github.com/Rixtayz/mcp-usage.git
cd mcp-usage
npm install && npm run build
node dist/bin/cli.js
| Option | Purpose |
|---|---|
--since <days> |
Look back this many days (default 30) |
--project <path> |
Only scan projects whose path contains this text |
--min-sessions <n> |
Sessions before an unused server is flagged (default 5) |
--dir <path> |
Claude config directory (default: $CLAUDE_CONFIG_DIR or ~/.claude) |
--json |
Print the full report as JSON, including per-tool stats |
Text output truncates long lists; --json always contains everything.
2. Connect to Claude Code
claude mcp add --scope user --transport stdio mcp-usage -- npx -y @rixtay/mcp-usage serve
3. Connect to Claude Desktop / Cowork / any MCP client
mcp-usage is listed in the official MCP Registry as io.github.Rixtayz/mcp-usage, so clients that browse the registry can install it by name. Otherwise, configure it by hand:
Edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS (or %APPDATA%\Claude\claude_desktop_config.json on Windows), reachable through Settings → Developer → Edit Config.
{
"mcpServers": {
"mcp-usage": {
"command": "npx",
"args": ["-y", "@rixtay/mcp-usage", "serve"]
}
}
}
If the host cannot find npx (it may not inherit your shell PATH), use absolute paths instead: "command": "/absolute/path/to/node", "args": ["/absolute/path/to/mcp-usage/dist/bin/cli.js", "serve"].
The server reads Claude Code's transcripts wherever it runs, so it only makes sense in local sessions, on the machine where you use Claude Code.
4. Example prompts
- "Which of my MCP servers should I disconnect?"
- "Which servers have been waiting for authorization the longest?"
- "Playwright seems flaky. Which of its tools fail the most?"
- "Did I use anything other than Context7 in the last 7 days?"
Typical flow: recommendations → the assistant proposes a cleanup list, you confirm → server_details on anything surprising → you disconnect the servers yourself. The tools never touch your MCP configuration.
What it reports
Each server gets one status:
| Status | Meaning |
|---|---|
used |
Called at least once in the window |
unused |
Its tools were available, but nothing ever called them |
failed |
Never exposed a tool; Claude Code reported a connection failure |
needs-auth |
Never exposed a tool; waiting for authorization |
Recommendations, in priority order:
| Action | Rule |
|---|---|
disconnect |
Unused, and available in ≥ 5 sessions (--min-sessions) |
fix-or-remove |
Failed to connect in ≥ 3 sessions |
authorize-or-remove |
Waiting for authorization in ≥ 3 sessions |
investigate-errors |
≥ 5 calls and ≥ 30 % of them failed |
heavy-results |
Results average ≥ 10,000 estimated tokens per call |
Development
npm test # vitest: name parsing, streaming parser, aggregation, rules, CLI, MCP tools over an in-memory transport
npm run typecheck
npm run inspect # MCP Inspector against the built server
Layout:
src/bin/cli.ts entry point: `mcp-usage` prints the report, `mcp-usage serve` serves stdio
src/cli.ts argument parsing and output
src/server.ts builds the McpServer and registers the four tools
src/analyze.ts options → report; the one function both shells call
src/parser.ts streaming JSONL reader → typed events
src/aggregate.ts events → per-server stats
src/recommend.ts stats → prioritized recommendations
src/report.ts text table rendering
src/scan.ts transcript discovery (--since, --project)
src/adapters/claude-code.ts the only client-specific code, behind a small ClientAdapter interface
src/names.ts `mcp__<server>__<tool>` parsing and server id mangling
Stack: @modelcontextprotocol/sdk v1, zod v4, nothing else at runtime. Design notes: docs/DESIGN.md.
Things worth knowing
- The transcript format is not a public API. It is parsed defensively — every field optional, unknown records ignored, malformed lines counted and skipped — but a future Claude Code release can still break it. Tested against Claude Code 2.1.233 – 2.1.274.
- Token figures are estimates: result bytes ÷ 4, text only. Transcripts record no per-result token count, and image results are not counted.
- Tool names are split on the first
__after themcp__prefix. Server ids can contain underscores, hyphens, dots or be a bare UUID, and tool names can contain__themselves, so a naivesplit("__")miscounts. - The same connector can appear under two names — a readable one in the CLI, a UUID in the desktop app. They are not merged.
- Servers bundled with the Claude desktop app (
ccd_*) are reported but never flagged for disconnection: you cannot remove them. - Claude Code deletes old transcripts, so a long
--sincewindow only sees what is still on disk. - Claude Code only, for now. Adapters for other clients are welcome.
Contributing
Bug reports, fixes and adapters for other MCP clients are welcome: see CONTRIBUTING.md. If Claude Code updates and the report suddenly looks wrong, open a bug with your Claude Code version. Found a way the tool could leak transcript content? Please report it privately, as described in SECURITY.md.
Release history: CHANGELOG.md.
License
MIT
usage MCP questions
How do I add usage MCP to Claude Code?
Run claude mcp add mcp-usage -- npx -y @rixtay/mcp-usage serve in your terminal. Add --scope user to make it available in every project.
How do I add usage 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 usage MCP provide?
It exposes 4 tools, including usage_summary, unused_servers, server_details, recommendations.
Is my conversation data private?
Yes, the server is private by construction with no network code. It only outputs server names, tool names, counts, and timestamps, never prompts, responses, or file paths.
What kind of information does the report provide?
It provides a summary of server status, tools exposed, session counts, call frequency, error rates, and estimated result tokens.