claude-status-mcp

Check your current Claude usage from the terminal, Claude Code, Codex, or any MCP client.

claude-status-mcp solves a small but annoying problem: Claude Code already has an OAuth session on your machine, but your current usage limits are not easy to query from a terminal or another agent. At the moment, Claude Code does not provide a native command for retrieving this usage data. For example, asking Claude with something like claude -p /usage will not return the structured usage information from Anthropic's usage endpoint.

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

This package fills that gap. It finds the local Claude OAuth token, calls Anthropic's OAuth usage API, and returns the usage JSON directly.

Demo

Features

• Reads Claude OAuth credentials from the places Claude Code already uses.
• Works on macOS, Linux, and Windows-style credential file setups.
• Exposes a single MCP tool: get_claude_usage.
• Runs without a daemon, database, or extra service.
• Does not store, log, or refresh your token.
• Supports explicit tokens through CLAUDE_OAUTH_ACCESS_TOKEN.
• --pretty flag for a human-readable terminal summary with progress bars.

Quick Start

Print your current usage in a terminal:

npx claude-status-mcp

Pretty-print for humans:

npx claude-status-mcp --pretty

Add it to Claude Code:

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

Add it to Codex:

codex mcp add claude-status-mcp -- npx -y claude-status-mcp --mcp

After adding the MCP server, restart Claude Code or Codex. Most MCP clients load servers when a new session starts.

Then ask your MCP client something like:

What is my current Claude usage?

Programmatic Usage

Install the package and import directly:

npm install claude-status-mcp

import { getClaudeUsage } from "claude-status-mcp";

const result = await getClaudeUsage();
console.log(result.usage.five_hour?.utilization); // e.g. 42

With options:

import { getClaudeUsage } from "claude-status-mcp";

const result = await getClaudeUsage({
  credentialsPath: "/path/to/credentials.json",
});

The package exports:

• getClaudeUsage(options?) — fetch current usage; returns ClaudeUsageResult
• getAccessToken(options?) — resolve OAuth token only; returns AccessTokenResult
• UsageApiError — thrown when the Anthropic API returns an error
• CredentialError — thrown when no token can be found

Requirements

• Node.js 18 or newer.
• Claude Code credentials on the machine, or a token provided through CLAUDE_OAUTH_ACCESS_TOKEN.

Token lookup order:

1. CLAUDE_OAUTH_ACCESS_TOKEN
2. macOS Keychain service Claude Code-credentials
3. ~/.claude/credentials.json

The credentials file should contain:

{
  "claudeAiOauth": {
    "accessToken": "sk-ant-..."
  }
}

CLI Usage

Run once with npx:

npx claude-status-mcp

Example output:

{
  "usage": {
    "five_hour": {
      "utilization": 42,
      "resets_at": "2026-05-19T12:30:00.000000+00:00"
    },
    "seven_day": {
      "utilization": 18,
      "resets_at": "2026-05-23T07:00:00.000000+00:00"
    }
  },
  "tokenSource": "macos-keychain"
}

Use a custom credentials file:

npx claude-status-mcp --credentials-path /path/to/credentials.json

Use an explicit token:

CLAUDE_OAUTH_ACCESS_TOKEN="sk-ant-..." npx claude-status-mcp

Show CLI help:

npx claude-status-mcp --help

Pretty output

npx claude-status-mcp --pretty

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Claude Usage
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Token source : macos-keychain
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 5h window
   [██████████░░░░░░░░░░] 48%
   Resets in 51m (2026-06-09T11:40:01Z)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 7d window
   [██████████████░░░░░░] 71%
   Resets in 92h 11m (2026-06-13T07:00:00Z)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 7d Sonnet window
   [██░░░░░░░░░░░░░░░░░░] 8%
   Resets in 92h 11m (2026-06-13T07:00:00Z)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All flags

npx claude-status-mcp [options]

Options:
  --pretty                   Human-readable summary with progress bars instead of JSON.
  --credentials-path <path>  Path to a credentials JSON file.
  --mcp                      Run as an MCP stdio server.
  --help, -h                 Show help.

MCP Setup

The MCP server exposes one tool:

get_claude_usage

It returns the same JSON as the CLI. The tool accepts one optional argument:

{
  "credentialsPath": "/path/to/credentials.json"
}

Claude Code

Add the published package:

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

Verify:

claude mcp list
claude mcp get claude-status-mcp

Equivalent MCP JSON:

{
  "mcpServers": {
    "claude-status-mcp": {
      "command": "npx",
      "args": ["-y", "claude-status-mcp", "--mcp"]
    }
  }
}

Codex

Add the published package:

codex mcp add claude-status-mcp -- npx -y claude-status-mcp --mcp

Verify:

codex mcp list
codex mcp get claude-status-mcp --json

Codex writes this to ~/.codex/config.toml:

[mcp_servers.claude-status-mcp]
command = "npx"
args = ["-y", "claude-status-mcp", "--mcp"]

Other MCP Clients

Use the same stdio server command:

{
  "mcpServers": {
    "claude-status-mcp": {
      "command": "npx",
      "args": ["-y", "claude-status-mcp", "--mcp"]
    }
  }
}

How It Works

claude-status-mcp is a thin wrapper around Claude Code's existing OAuth session.

When you run the CLI or call the MCP tool, it finds an access token from your environment, the macOS Keychain, or a Claude credentials file. Then it sends one authenticated request to Anthropic's OAuth usage endpoint:

GET https://api.anthropic.com/api/oauth/usage

The API response is returned as JSON. In CLI mode, it is printed to stdout. In MCP mode, it is returned from get_claude_usage so Claude Code, Codex, or another MCP client can inspect it during a session.

There is no background process in CLI mode. The command reads credentials, calls the API, prints the result, and exits. In MCP mode, the process stays alive because the MCP client manages it over stdio.

Test With Raw Shell

You can test the underlying API call without this package.

On macOS, read the token from Claude Code's Keychain item:

export CLAUDE_OAUTH_ACCESS_TOKEN="$(
  security find-generic-password -s "Claude Code-credentials" -w \
    | node -e 'let input=""; process.stdin.on("data", c => input += c); process.stdin.on("end", () => console.log(JSON.parse(input).claudeAiOauth.accessToken));'
)"

On Linux or Windows, read the token from the credentials file:

export CLAUDE_OAUTH_ACCESS_TOKEN="$(
  node -e 'const fs = require("fs"); const path = require("os").homedir() + "/.claude/credentials.json"; console.log(JSON.parse(fs.readFileSync(path, "utf8")).claudeAiOauth.accessToken);'
)"

Or set a token directly:

export CLAUDE_OAUTH_ACCESS_TOKEN="sk-ant-..."

Then call the usage API:

curl --request GET \
  --url https://api.anthropic.com/api/oauth/usage \
  --header "Authorization: Bearer $CLAUDE_OAUTH_ACCESS_TOKEN" \
  --header "anthropic-beta: oauth-2025-04-20" \
  --header "Content-Type: application/json"

Local Checkout Setup

Use these commands when working from a cloned copy of this repository before publishing to npm.

Install and build:

npm install
npm run build

Run the local CLI:

node dist/cli.js

Run the local MCP server:

node dist/cli.js --mcp

Claude Code From Local Checkout

Use the compiled entrypoint:

claude mcp add --scope user claude-status-mcp -- node /absolute/path/to/claude-status-mcp/dist/cli.js --mcp

Or run TypeScript directly with tsx:

claude mcp add --scope user claude-status-mcp -- npx tsx /absolute/path/to/claude-status-mcp/src/cli.ts --mcp

Codex From Local Checkout

Use the compiled entrypoint:

codex mcp add claude-status-mcp -- node /absolute/path/to/claude-status-mcp/dist/cli.js --mcp

Or run TypeScript directly with tsx:

codex mcp add claude-status-mcp -- npx tsx /absolute/path/to/claude-status-mcp/src/cli.ts --mcp

Development

Install dependencies:

npm install

Run from TypeScript:

npm run dev

Run the MCP server from TypeScript:

npm run dev -- --mcp

Build:

npm run build

Typecheck:

npm run typecheck

Preview the npm package:

npm pack --dry-run

Troubleshooting

Unable to Find a Claude OAuth Access Token

Make sure Claude Code is logged in on this machine, or pass a token explicitly:

CLAUDE_OAUTH_ACCESS_TOKEN="sk-ant-..." npx claude-status-mcp

You can also point the command or MCP tool at a credentials file:

npx claude-status-mcp --credentials-path /path/to/credentials.json

MCP Tool Does Not Show Up

Restart Claude Code, Codex, or your MCP client after adding the server. Most MCP clients discover tools only when a new session starts.

macOS Keychain Works in Terminal But Not in a Sandbox

Some sandboxed environments cannot access the macOS Keychain. In that case, run outside the sandbox or provide CLAUDE_OAUTH_ACCESS_TOKEN explicitly.

Security Notes

This package reads an OAuth access token so it can call Anthropic's usage API. Treat that token like a secret.

• Do not commit credentials files.
• Do not paste tokens into shared logs.
• Prefer the macOS Keychain or environment variables over hardcoded config.
• The package returns token source metadata, not the token value.

Related Packages

These packages are part of the same family of AI provider status tools:

• codex-status-mcp — Codex / ChatGPT rate-limit windows and credits
• copilot-status-mcp — GitHub Copilot session, weekly, and monthly quota
• provider-status-mcp — Aggregates Claude, Codex, and Copilot status into a single view

License

MIT

Made with ❤️ by Dmytro Vakulenko, 2026