Skip to main content
The @ccusage/mcp package provides a Model Context Protocol (MCP) server that exposes ccusage functionality to MCP-compatible clients like Claude Desktop. This enables real-time usage tracking directly within your AI workflows.

​
What is MCP?

Model Context Protocol (MCP) is an open protocol that enables AI applications to access external data sources and tools. The ccusage MCP server exposes your Claude Code usage data as MCP tools that can be called from Claude Desktop conversations.

​
Installation

​
Quick Start

# Using bunx (recommended for speed)
bunx @ccusage/mcp@latest

# Using npx
npx @ccusage/mcp@latest

# View available options
npx @ccusage/mcp@latest -- --help

​
Transport Options

The MCP server supports multiple transport protocols:
Standard input/output transport for process-based communication.
npx @ccusage/mcp@latest
Best for: Claude Desktop, local MCP clients

​
Claude Desktop Integration

Integrate ccusage into Claude Desktop to query your usage data during conversations.

​
Configuration

Add to your Claude Desktop MCP configuration file:
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "ccusage": {
      "command": "npx",
      "args": ["@ccusage/mcp@latest"],
      "type": "stdio"
    }
  }
}
After updating the configuration, restart Claude Desktop for changes to take effect.

​
Using in Conversations

Once configured, you can ask Claude Desktop questions about your usage: 
"What's my Claude Code usage today?"
Claude will use the MCP tools to fetch your actual usage data and provide accurate answers.

​
Claude Code Integration

Add ccusage MCP server to Claude Code: 
claude mcp add ccusage npx -- @ccusage/mcp@latest
This enables Claude Code to access its own usage data through the MCP protocol.

​
Available MCP Tools

The ccusage MCP server provides four tools matching the main CLI commands:

​
daily

Retrieve daily usage reports with token counts and costs.
​
since
string
Start date in YYYYMMDD format (optional)
​
until
string
End date in YYYYMMDD format (optional)
​
breakdown
boolean
Include per-model cost breakdown (optional, default: false)
​
mode
string
Cost calculation mode: auto, calculate, or display (optional, default: auto)
Example Response: 
{
  "dailyUsage": [
    {
      "date": "2025-03-04",
      "inputTokens": 15234,
      "outputTokens": 8923,
      "cacheCreationTokens": 2341,
      "cacheReadTokens": 12567,
      "totalTokens": 39065,
      "totalCost": 0.0456,
      "modelsUsed": ["claude-sonnet-4-20250514"]
    }
  ]
}

​
monthly

Retrieve monthly aggregated usage reports.
​
mode
string
Cost calculation mode: auto, calculate, or display (optional, default: auto)
Example Response: 
{
  "monthlyUsage": [
    {
      "month": "2025-03",
      "inputTokens": 456789,
      "outputTokens": 234567,
      "cacheCreationTokens": 45678,
      "cacheReadTokens": 123456,
      "totalTokens": 860490,
      "totalCost": 1.2345,
      "modelsUsed": ["claude-sonnet-4-20250514", "claude-opus-4-20250514"]
    }
  ]
}

​
session

Retrieve usage grouped by conversation sessions (projects).
​
mode
string
Cost calculation mode: auto, calculate, or display (optional, default: auto)
Example Response: 
{
  "sessionUsage": [
    {
      "sessionId": "my-project",
      "projectPath": "/path/to/my-project",
      "inputTokens": 45678,
      "outputTokens": 23456,
      "cacheCreationTokens": 4567,
      "cacheReadTokens": 12345,
      "totalCost": 0.2345,
      "lastActivity": "2025-03-04T15:30:00Z",
      "modelsUsed": ["claude-sonnet-4-20250514"]
    }
  ]
}

​
blocks

Retrieve usage organized by 5-hour billing windows.
​
active
boolean
Show only active block with projections (optional, default: false)
​
recent
boolean
Show blocks from last 3 days including active (optional, default: false)
​
mode
string
Cost calculation mode: auto, calculate, or display (optional, default: auto)
Example Response: 
{
  "blocks": [
    {
      "blockStart": "2025-03-04T10:00:00Z",
      "blockEnd": "2025-03-04T15:00:00Z",
      "inputTokens": 12345,
      "outputTokens": 6789,
      "cacheCreationTokens": 1234,
      "cacheReadTokens": 5678,
      "totalTokens": 26046,
      "totalCost": 0.0345,
      "isActive": true,
      "modelsUsed": ["claude-sonnet-4-20250514"]
    }
  ]
}

​
HTTP Server

For web applications, run the MCP server with HTTP transport: 
npx @ccusage/mcp@latest -- --type http --port 8080

​
API Endpoints

The HTTP server exposes MCP protocol endpoints: 
curl http://localhost:8080/mcp/tools
The HTTP server is intended for local development and trusted networks. Do not expose it to the public internet without proper authentication and encryption.

​
Custom Client Integration

Integrate ccusage MCP server into your own MCP client: 
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Create transport
const transport = new StdioClientTransport({
  command: 'npx',
  args: ['@ccusage/mcp@latest'],
});

// Create client
const client = new Client({
  name: 'my-app',
  version: '1.0.0',
}, {
  capabilities: {}
});

// Connect
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools);

// Call daily tool
const result = await client.callTool({
  name: 'daily',
  arguments: {
    since: '20250301',
    until: '20250307',
    breakdown: true
  }
});

console.log('Daily usage:', result);

​
Configuration

The MCP server respects the same environment variables as the CLI:
​
CLAUDE_CONFIG_DIR
string
Custom Claude data directory paths (comma-separated for multiple paths)
export CLAUDE_CONFIG_DIR="/path/to/claude1,/path/to/claude2"
npx @ccusage/mcp@latest
​
LOG_LEVEL
number
Logging verbosity (0=silent, 1=warn, 2=log, 3=info, 4=debug, 5=trace)
LOG_LEVEL=4 npx @ccusage/mcp@latest

​
Troubleshooting

​
Claude Desktop Not Detecting Server

  1. Verify the configuration file path for your OS
  2. Check JSON syntax with a validator
  3. Restart Claude Desktop completely
  4. Check Claude Desktop logs for error messages

​
Connection Timeouts

# Increase timeout with environment variable
MCP_TIMEOUT=30000 npx @ccusage/mcp@latest

​
Permission Errors

Ensure the MCP server has access to Claude data directories: 
# Check directory permissions
ls -la ~/.config/claude/projects/
ls -la ~/.claude/projects/

# Fix permissions if needed
chmod -R u+r ~/.config/claude/projects/

​
Debugging

Enable debug logging: 
LOG_LEVEL=4 npx @ccusage/mcp@latest
For more details on Model Context Protocol, visit modelcontextprotocol.io

Build docs developers (and LLMs) love

Get started for freeTalk to us