Skip to main content

​
@ccusage/mcp

Model Context Protocol (MCP) server implementation for ccusage - provides Claude Code usage data through the MCP protocol for real-time integration with Claude Desktop and other MCP-compatible tools.

​
Quick Start

bunx @ccusage/mcp@latest

​
What is MCP?

The Model Context Protocol is an open standard that enables AI applications to securely access external data sources and tools. The @ccusage/mcp server exposes ccusage data and functionality through this protocol.

​
Installation

​
Claude Desktop Integration

Add to your Claude Desktop MCP configuration file: macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json 
{
  "mcpServers": {
    "ccusage": {
      "command": "npx",
      "args": ["@ccusage/mcp@latest"],
      "type": "stdio"
    }
  }
}
Restart Claude Desktop to activate the integration.

​
Claude Code Integration

Add the MCP server to Claude Code: 
claude mcp add ccusage npx -- @ccusage/mcp@latest

​
Available Tools

Once configured, the following tools become available in Claude Desktop:

daily

Get daily usage reports with token counts and costs

monthly

Get monthly aggregated usage reports

session

Get session-based usage reports grouped by conversation

blocks

Get 5-hour billing blocks usage reports

​
Usage in Claude Desktop

Once configured, you can ask Claude Desktop questions like:
  • “Show me my Claude Code usage from last week”
  • “What are my total costs for this month?”
  • “Which models did I use yesterday?”
  • “Show my most expensive conversation sessions”
Claude Desktop will automatically use the MCP tools to fetch and display your usage data.

​
Transport Options

The MCP server supports multiple transport protocols:

​
STDIO Transport (Default)

Used for Claude Desktop integration: 
{
  "command": "npx",
  "args": ["@ccusage/mcp@latest"],
  "type": "stdio"
}

​
HTTP Transport

For web-based integrations: 
bunx @ccusage/mcp@latest -- --type http --port 8080
Options:
  • --type http - Enable HTTP transport
  • --port <number> - Specify port (default: 3000)
  • --host <string> - Specify host (default: localhost)

​
Features

Real-time Data

Access current usage data directly from Claude Desktop

Multiple Reports

Daily, monthly, session, and blocks reports available

Secure Access

Local data access with no external API calls required

Standard Protocol

Uses open MCP standard for broad compatibility

​
Data Source

The MCP server reads from the same data sources as the ccusage CLI:
  • Claude Code: ~/.claude/projects/ or ~/.config/claude/projects/
  • Supports custom paths via CLAUDE_CONFIG_DIR environment variable
  • Automatic discovery of both old and new Claude data directories

​
Example Queries

Here are some example questions you can ask Claude Desktop:

​
Cost Analysis

“What were my Claude Code costs last month?”
Claude will use the monthly tool to fetch and display your monthly usage.

​
Model Usage

“Which Claude models did I use this week?”
Claude will use the daily tool with date filters to show model usage.

​
Session Breakdown

“Show me my most expensive conversation sessions”
Claude will use the session tool to list sessions sorted by cost.

​
Billing Windows

“Am I close to my 5-hour block limit?”
Claude will use the blocks tool to show your current billing window usage.

​
Configuration

The MCP server respects the same environment variables as ccusage:
VariableDescriptionDefault
CLAUDE_CONFIG_DIRCustom Claude data directory paths~/.claude,~/.config/claude
LOG_LEVELControl logging verbosity (0-5)-

​
Troubleshooting

​
Server Not Appearing in Claude Desktop

  1. Check your config file syntax is valid JSON
  2. Ensure the path to claude_desktop_config.json is correct
  3. Restart Claude Desktop after making changes
  4. Check the Claude Desktop logs for errors

​
Permission Issues

  • Ensure the MCP server has read access to your Claude data directories
  • On macOS/Linux, check file permissions with ls -la ~/.claude/

​
Connection Errors

For HTTP transport:
  • Verify the port is not already in use
  • Check firewall settings allow the connection
  • Try a different port with --port flag

​
Architecture

The MCP server is built with:
  • @hono/mcp - MCP implementation for Hono
  • @modelcontextprotocol/sdk - Official MCP SDK
  • Hono - Fast, lightweight web framework
  • ccusage - Core usage analysis functionality

npm Package

View on npm registry

MCP Specification

Learn about Model Context Protocol

ccusage Family

Explore all related tools

Claude Desktop

Download Claude Desktop

Build docs developers (and LLMs) love

Get started for freeTalk to us