MCP.so
Sign In

Claude Usage Mcp

@Orellius

Repository

About Claude Usage Mcp

MCP server for Claude Pro/Max subscription usage — session limits, weekly limits, per-model breakdown, extra credits. Zero config, reads your existing OAuth token.

#cli#oauth#subscription#typescript#mcp#rate-limits#max#usage#developer-tools#statusline#pro#claude#anthropic#model-context-protocol#claude-code

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "claudeusage": {
      "command": "node",
      "args": [
        "/absolute/path/to/claudeusage-mcp/dist/index.js"
      ]
    }
  }
}

Tools

4

Full dashboard — session, weekly, per-model, extra usage with progress bars

Current 5-hour session window only

7-day limits with per-model breakdown (All, Opus, Sonnet)

Am I about to be rate-limited? Returns LOW / MODERATE / HIGH / RATE LIMITED

Overview

What is Claude Usage Mcp?

Claude Usage Mcp is an MCP server that gives real‑time visibility into your Claude Pro/Max subscription usage directly inside Claude Code. It reads the OAuth token already stored on your machine and calls Anthropic’s usage endpoint—no API keys, scraping, or browser automation required.

How to use Claude Usage Mcp?

Clone the repository, run npm install && npm run build, then add the server via claude mcp add claudeusage -- node $(pwd)/dist/index.js or manually in your MCP config. After restarting Claude Code, ask “what’s my usage?” or type /usage. Optional statusline integration adds a persistent usage line.

Key features of Claude Usage Mcp

  • Reads OAuth credentials from macOS Keychain or ~/.claude/.credentials.json
  • Provides four MCP tools: get_usage, get_session_usage, get_weekly_limits, check_rate_status
  • Caches responses for 60 seconds with stale‑data fallback on rate limits
  • Color‑coded progress bars (green/orange/red) for usage levels
  • Statusline script shows usage in the Claude Code status bar
  • Works on macOS and Linux with Node.js 18+

Use cases of Claude Usage Mcp

  • Monitor current 5‑hour session window utilization and reset countdown
  • Check weekly usage across all models and per‑model (Opus, Sonnet)
  • See if you are approaching or currently rate‑limited
  • Track extra usage credits and monthly limits
  • Get all usage data without leaving the terminal or opening a browser

FAQ from Claude Usage Mcp

How does Claude Usage Mcp authenticate?

It uses the same OAuth token that Claude Code creates when you sign in with a Pro/Max subscription. No API keys, environment variables, or .env files are required.

What are the runtime requirements?

Node.js 18 or later, macOS or Linux, and a Claude Code session logged in with a Pro or Max subscription.

Where does my usage data come from?

The server calls GET https://api.anthropic.com/api/oauth/usage with the stored OAuth token. It caches the response for 60 seconds and serves stale data if the endpoint rate‑limits the request.

Does Claude Usage Mcp work with API keys?

No. This server is for Pro/Max subscribers only. API users should use the official Usage and Cost API instead.

What happens if my token expires?

Restart Claude Code to trigger a fresh OAuth login. If you previously used claude setup-token or /login, the token may have the wrong scopes; delete the credentials file and restart Claude Code.

Frequently asked questions

How does Claude Usage Mcp authenticate?

It uses the same OAuth token that Claude Code creates when you sign in with a Pro/Max subscription. No API keys, environment variables, or `.env` files are required.

What are the runtime requirements?

Node.js 18 or later, macOS or Linux, and a Claude Code session logged in with a Pro or Max subscription.

Where does my usage data come from?

The server calls `GET https://api.anthropic.com/api/oauth/usage` with the stored OAuth token. It caches the response for 60 seconds and serves stale data if the endpoint rate‑limits the request.

Does Claude Usage Mcp work with API keys?

No. This server is for Pro/Max subscribers only. API users should use the official [Usage and Cost API](https://platform.claude.com/docs/en/build-with-claude/usage-cost-api) instead.

What happens if my token expires?

Restart Claude Code to trigger a fresh OAuth login. If you previously used `claude setup-token` or `/login`, the token may have the wrong scopes; delete the credentials file and restart Claude Code.

Comments

Basic information

Category

AI & Agents

Transports

stdio

Author

Orellius

Submitted by

Orel

More AI & Agents MCP servers

欢迎来到 智言平台

Shy2593666979

AgentChat 是一个基于 LLM 的智能体交流平台，内置默认 Agent 并支持用户自定义 Agent。通过多轮对话和任务协作，Agent 可以理解并协助完成复杂任务。项目集成 LangChain、Function Call、MCP 协议、RAG、Memory、HITL、Skill、Milvus 和 ElasticSearch 等技术，实现高效的知识检索与工具调用，使用 FastAPI 构建高性能后端服务。

797

Transform MCP

Unstructured

The Unstructured Transform MCP Server connects your ADK agent to Unstructured, a document processing platform that turns raw files into structured, AI-ready data. This integration gives your agent the ability to parse PD

Model Context Protocol Server for Home Assistant

tevonsb

A MCP server for Home Assistant

574

Model Context Protocol for Unreal Engine

chongdashu

Enable AI assistant clients like Cursor, Windsurf and Claude Desktop to control Unreal Engine through natural language using the Model Context Protocol (MCP).

2.0K

Hass-MCP

voska

Control and query Home Assistant from Claude and other LLMs — a Model Context Protocol (MCP) server.

307