@anatoly314/claude-usage-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anatoly Tarnavsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,82 @@
+# claude-usage-mcp
+
+An MCP server that reports your real Claude subscription usage — 5-hour
+session window, weekly limit, and per-model limits — pulled from the same
+endpoint Claude Code's `/usage` command uses.
+
+## Requirements
+
+- macOS or Linux
+- Node.js 20+
+- Claude Code logged in on a Pro, Max, or Team plan
+
+This server reads Claude Code's own OAuth access token (from the macOS
+Keychain, or `~/.claude/.credentials.json` as a fallback). It never asks for
+or stores credentials itself.
+
+## Install / configure
+
+Add to your `.mcp.json`.
+
+Local build:
+
+```json
+{
+  "mcpServers": {
+    "claude-usage": {
+      "command": "node",
+      "args": ["/path/to/claude-usage-mcp/dist/index.js"]
+    }
+  }
+}
+```
+
+Or via npx:
+
+```json
+{
+  "mcpServers": {
+    "claude-usage": {
+      "command": "npx",
+      "args": ["-y", "@anatoly314/claude-usage-mcp"]
+    }
+  }
+}
+```
+
+## Tool
+
+### `get_usage`
+
+Takes no arguments. Returns the current usage snapshot as JSON.
+
+```json
+{
+  "session_5h": { "utilization_percent": 42, "resets_at": "2026-09-01T18:00:00Z" },
+  "weekly_7d": { "utilization_percent": 61, "resets_at": "2026-09-05T00:00:00Z" },
+  "model_limits": [
+    {
+      "model": "Opus",
+      "kind": "weekly_scoped",
+      "utilization_percent": 51,
+      "resets_at": "2026-09-05T00:00:00Z",
+      "is_active": true
+    }
+  ],
+  "fetched_at": "2026-09-01T15:04:00Z",
+  "stale": false
+}
+```
+
+If a fetch fails, the last successful response is served instead with
+`stale: true` and `stale_age_seconds` set.
+
+## Notes
+
+- This uses an undocumented Anthropic endpoint. It may change or break
+  without notice.
+- Responses are cached for 120 seconds; after a failed fetch, further
+  requests back off for 60 seconds before retrying, to avoid hammering the
+  API.
+- Everything stays local — no data leaves your machine except the request to
+  Anthropic's usage endpoint.

package/dist/credentials.js

@@ -0,0 +1,90 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const execFileAsync = promisify(execFile);
+const KEYCHAIN_SERVICE = "Claude Code-credentials";
+const FALLBACK_CREDENTIALS_PATH = join(homedir(), ".claude", ".credentials.json");
+const KEYCHAIN_TIMEOUT_MS = 5000;
+export class CredentialsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CredentialsError";
+    }
+}
+function extractAccessToken(raw, source) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new CredentialsError(`Credentials at ${source} did not contain valid JSON.`);
+    }
+    const token = parsed.claudeAiOauth?.accessToken;
+    if (!token || typeof token !== "string") {
+        throw new CredentialsError(`Credentials at ${source} did not contain a claudeAiOauth.accessToken field.`);
+    }
+    return token;
+}
+// A locked Keychain, non-macOS, or a missing entry are all expected/benign
+// and would otherwise log on every cache-miss call; warn about them once
+// per process instead of spamming stderr.
+let keychainMissWarned = false;
+function warnKeychainMissOnce(err) {
+    if (keychainMissWarned)
+        return;
+    keychainMissWarned = true;
+    console.error(`[credentials] Keychain lookup failed, falling back to file: ${err instanceof Error ? err.message : String(err)}`);
+}
+async function readFromKeychain() {
+    let stdout;
+    try {
+        ({ stdout } = await execFileAsync("security", ["find-generic-password", "-s", KEYCHAIN_SERVICE, "-w"], { timeout: KEYCHAIN_TIMEOUT_MS, maxBuffer: 1_000_000 }));
+    }
+    catch (err) {
+        // Keychain entry not found, `security` unavailable (non-macOS), user
+        // denied access, or a locked Keychain timed out waiting on a GUI prompt.
+        warnKeychainMissOnce(err);
+        return { token: null };
+    }
+    try {
+        return { token: extractAccessToken(stdout.trim(), "macOS Keychain") };
+    }
+    catch (err) {
+        const credErr = err instanceof CredentialsError ? err : new CredentialsError(String(err));
+        console.error(`[credentials] Keychain entry found but could not be parsed: ${credErr.message}`);
+        return { token: null, malformedError: credErr };
+    }
+}
+async function readFromFile() {
+    try {
+        const raw = await readFile(FALLBACK_CREDENTIALS_PATH, "utf8");
+        return extractAccessToken(raw, FALLBACK_CREDENTIALS_PATH);
+    }
+    catch (err) {
+        console.error(`[credentials] File lookup failed at ${FALLBACK_CREDENTIALS_PATH}: ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    }
+}
+/**
+ * Reads the current Claude Code OAuth access token fresh from disk/keychain.
+ * Never caches — Claude Code may refresh the token out-of-band and we must
+ * always pick up the latest one.
+ */
+export async function getAccessToken() {
+    const keychainResult = await readFromKeychain();
+    if (keychainResult.token)
+        return keychainResult.token;
+    const fromFile = await readFromFile();
+    if (fromFile)
+        return fromFile;
+    if (keychainResult.malformedError) {
+        throw new CredentialsError(`Keychain entry "${KEYCHAIN_SERVICE}" was found but could not be parsed ` +
+            `(${keychainResult.malformedError.message}), and no valid credentials were found at ` +
+            `${FALLBACK_CREDENTIALS_PATH} either. Make sure you are logged in via \`claude\` (Claude Code CLI).`);
+    }
+    throw new CredentialsError("No Claude Code credentials found. Checked macOS Keychain " +
+        `("${KEYCHAIN_SERVICE}") and ${FALLBACK_CREDENTIALS_PATH}. ` +
+        "Make sure you are logged in via `claude` (Claude Code CLI).");
+}

package/dist/index.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { getUsage, UsageAuthError, UsageFetchError } from "./usage.js";
+import { CredentialsError } from "./credentials.js";
+const server = new McpServer({
+    name: "claude-usage-mcp",
+    version: "0.1.0",
+});
+server.registerTool("get_usage", {
+    description: "Report the current user's Claude subscription usage: 5-hour session window, " +
+        "7-day weekly limit, and any per-model weekly limits, as utilization " +
+        "percentages with reset timestamps.",
+    inputSchema: {},
+}, async () => {
+    try {
+        const usage = await getUsage();
+        return {
+            content: [{ type: "text", text: JSON.stringify(usage, null, 2) }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof UsageAuthError || err instanceof CredentialsError || err instanceof UsageFetchError
+            ? err.message
+            : `Unexpected error fetching usage: ${err instanceof Error ? err.message : String(err)}`;
+        console.error(`[get_usage] ${message}`);
+        return {
+            content: [{ type: "text", text: message }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("claude-usage-mcp server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error starting claude-usage-mcp:", err);
+    process.exit(1);
+});

package/dist/usage.js

@@ -0,0 +1,189 @@
+import { getAccessToken } from "./credentials.js";
+const USAGE_URL = "https://api.anthropic.com/api/oauth/usage";
+const ANTHROPIC_BETA_HEADER = "oauth-2025-04-20";
+// Must resemble a real Claude Code version string — without a plausible
+// User-Agent this endpoint routes requests into an aggressively
+// rate-limited bucket (persistent 429s).
+const USER_AGENT = "claude-code/2.1.252";
+const CACHE_TTL_MS = 120_000;
+const BACKOFF_MS = 60_000;
+export class UsageAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UsageAuthError";
+    }
+}
+export class UsageFetchError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "UsageFetchError";
+    }
+}
+let cache = null;
+let inFlight = null;
+// Set after a failed fetch (429/5xx/network/parse error) so we don't hammer
+// the API on every call while it's down; cleared on the next success.
+let nextRetryAtMs = 0;
+function mapPool(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const v = value;
+    const utilization = typeof v.utilization === "number" ? v.utilization : null;
+    const resetsAt = typeof v.resets_at === "string" ? v.resets_at : null;
+    return { utilization_percent: utilization, resets_at: resetsAt };
+}
+/**
+ * The endpoint's top-level `seven_day_opus`/`seven_day_sonnet` fields are
+ * legacy and always null — real per-model data lives in the `limits[]`
+ * array as entries like:
+ *   {"kind":"weekly_scoped","percent":51,"resets_at":"...",
+ *    "scope":{"model":{"id":null,"display_name":"Fable"}},"is_active":true}
+ * Parse defensively: `limits` may be missing, not an array, or contain
+ * malformed elements, and model names are never hardcoded here.
+ */
+function parseModelLimits(value) {
+    if (!Array.isArray(value))
+        return [];
+    const results = [];
+    for (const entry of value) {
+        if (!entry || typeof entry !== "object")
+            continue;
+        const e = entry;
+        const scope = e.scope && typeof e.scope === "object" ? e.scope : null;
+        const modelScope = scope && scope.model && typeof scope.model === "object"
+            ? scope.model
+            : null;
+        if (!modelScope)
+            continue;
+        const displayName = typeof modelScope.display_name === "string" ? modelScope.display_name : null;
+        const id = typeof modelScope.id === "string" ? modelScope.id : null;
+        const model = displayName ?? id ?? "unknown";
+        const percent = typeof e.percent === "number" ? e.percent : null;
+        const resetsAt = typeof e.resets_at === "string" ? e.resets_at : null;
+        const isActive = typeof e.is_active === "boolean" ? e.is_active : null;
+        const kind = typeof e.kind === "string" ? e.kind : null;
+        results.push({ model, kind, utilization_percent: percent, resets_at: resetsAt, is_active: isActive });
+    }
+    return results;
+}
+function parseUsageResponse(json) {
+    const obj = json && typeof json === "object" ? json : {};
+    return {
+        session_5h: mapPool(obj.five_hour),
+        weekly_7d: mapPool(obj.seven_day),
+        model_limits: parseModelLimits(obj.limits),
+        fetched_at: new Date().toISOString(),
+        stale: false,
+        // The endpoint is undocumented and carries several other fields (spend/
+        // credit info, feature flags, ...) beyond what's modeled above — keep
+        // the full response around rather than silently dropping data.
+        raw: obj,
+    };
+}
+function withStale(entry, reason) {
+    const staleAgeSeconds = Math.round((Date.now() - entry.fetchedAtMs) / 1000);
+    return { ...entry.result, stale: true, stale_reason: reason, stale_age_seconds: staleAgeSeconds };
+}
+async function fetchUsage() {
+    // Read fresh on every cache miss: Claude Code may have refreshed the
+    // token out-of-band and we must pick up the latest one. We never attempt
+    // to refresh it ourselves.
+    const token = await getAccessToken();
+    let response;
+    try {
+        response = await fetch(USAGE_URL, {
+            headers: {
+                Authorization: `Bearer ${token}`,
+                "anthropic-beta": ANTHROPIC_BETA_HEADER,
+                "User-Agent": USER_AGENT,
+            },
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        nextRetryAtMs = Date.now() + BACKOFF_MS;
+        if (cache) {
+            console.error(`[usage] network error, serving stale cache: ${message}`);
+            return withStale(cache, `network error: ${message}`);
+        }
+        throw new UsageFetchError(`Network error fetching usage: ${message}`);
+    }
+    if (response.status === 401) {
+        const bodyText = await response.text().catch(() => "");
+        throw new UsageAuthError("Authentication failed (401) — the Claude Code access token is invalid or expired. " +
+            "Run `claude` to sign in again. " +
+            `Response: ${bodyText.slice(0, 300)}`);
+    }
+    if (response.status === 429 || response.status >= 500) {
+        const bodyText = await response.text().catch(() => "");
+        nextRetryAtMs = Date.now() + BACKOFF_MS;
+        if (cache) {
+            console.error(`[usage] usage API returned ${response.status}, serving stale cache. Body: ${bodyText.slice(0, 300)}`);
+            return withStale(cache, `HTTP ${response.status} from usage API`);
+        }
+        throw new UsageFetchError(`Usage API returned ${response.status} and no cached data is available yet. Body: ${bodyText.slice(0, 300)}`);
+    }
+    if (!response.ok) {
+        const bodyText = await response.text().catch(() => "");
+        nextRetryAtMs = Date.now() + BACKOFF_MS;
+        if (cache) {
+            console.error(`[usage] usage API returned unexpected status ${response.status}, serving stale cache. Body: ${bodyText.slice(0, 300)}`);
+            return withStale(cache, `HTTP ${response.status} from usage API`);
+        }
+        throw new UsageFetchError(`Usage API returned unexpected status ${response.status}. Body: ${bodyText.slice(0, 300)}`);
+    }
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch {
+        nextRetryAtMs = Date.now() + BACKOFF_MS;
+        if (cache) {
+            console.error("[usage] failed to parse usage API response as JSON, serving stale cache");
+            return withStale(cache, "failed to parse usage API response as JSON");
+        }
+        throw new UsageFetchError("Usage API returned a response that could not be parsed as JSON.");
+    }
+    const result = parseUsageResponse(json);
+    // Capture the write time fresh here (not at the start of the request) so
+    // the cache TTL and the user-visible fetched_at reflect when the response
+    // actually arrived, not when the fetch was kicked off.
+    const fetchedAtMs = Date.now();
+    result.fetched_at = new Date(fetchedAtMs).toISOString();
+    cache = { result, fetchedAtMs };
+    nextRetryAtMs = 0;
+    return result;
+}
+/**
+ * Fetches usage, using an in-memory cache (120s TTL). On 429/5xx/network
+ * errors, falls back to the last successful response (marked stale) if one
+ * is cached. On 401, never serves stale data — surfaces the auth problem.
+ * Concurrent cache-misses share a single in-flight request.
+ *
+ * After a failure, a 60s backoff window applies: further calls skip the
+ * network entirely and either serve the stale cache or rethrow the error
+ * result, until the window elapses.
+ */
+export async function getUsage() {
+    const now = Date.now();
+    if (cache && now - cache.fetchedAtMs < CACHE_TTL_MS) {
+        return cache.result;
+    }
+    if (now < nextRetryAtMs) {
+        if (cache) {
+            return withStale(cache, "backing off after a previous fetch failure");
+        }
+        throw new UsageFetchError(`Usage API fetch failed previously and no cached data is available; ` +
+            `backing off until ${new Date(nextRetryAtMs).toISOString()}.`);
+    }
+    if (inFlight) {
+        return inFlight;
+    }
+    inFlight = fetchUsage();
+    try {
+        return await inFlight;
+    }
+    finally {
+        inFlight = null;
+    }
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@anatoly314/claude-usage-mcp",
+  "version": "0.1.0",
+  "description": "MCP server exposing Claude subscription usage (session/weekly/per-model limits)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "claude-usage-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run clean && npm run build",
+    "pack:local": "rm -f *.tgz && npm run clean && npm run build && npm pack",
+    "install:local": "npm install -g ./anatoly314-claude-usage-mcp-*.tgz",
+    "uninstall:local": "npm uninstall -g @anatoly314/claude-usage-mcp"
+  },
+  "keywords": ["mcp", "claude", "claude-code", "usage", "model-context-protocol"],
+  "author": "Anatoly Tarnavsky",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/anatoly-lab/claude-usage-mcp"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "typescript": "^7.0.2"
+  }
+}