ccusage 0.4.2 → 0.6.0

package/README.md

@@ -38,12 +38,13 @@ This tool helps you understand the value you're getting from your subscription b
 ## Features
 
 - 📊 **Daily Report**: View token usage and costs aggregated by date
+- 📅 **Monthly Report**: View token usage and costs aggregated by month
 - 💬 **Session Report**: View usage grouped by conversation sessions
 - 📅 **Date Filtering**: Filter reports by date range using `--since` and `--until`
 - 📁 **Custom Path**: Support for custom Claude data directory locations
 - 🎨 **Beautiful Output**: Colorful table-formatted display
 - 📄 **JSON Output**: Export data in structured JSON format with `--json`
-- 💰 **Cost Tracking**: Shows costs in USD for each day/session
+- 💰 **Cost Tracking**: Shows costs in USD for each day/month/session
 - 🔄 **Cache Token Support**: Tracks and displays cache creation and cache read tokens separately
 
 ## Important Disclaimer
@@ -73,6 +74,12 @@ npx ccusage@latest
 
 # Using bunx
 bunx ccusage
+
+# Using pnpm
+pnpm dlx ccusage
+
+# Using Deno with security flags
+deno run -E -R=$HOME/.claude/projects/ -S=homedir -N='raw.githubusercontent.com:443' npm:ccusage@latest
 ```
 
 ### Local Installation
@@ -128,10 +135,41 @@ ccusage daily --json
 ccusage daily --mode auto       # Use costUSD when available, calculate otherwise (default)
 ccusage daily --mode calculate  # Always calculate costs from tokens
 ccusage daily --mode display    # Always show pre-calculated costUSD values
+
+# Control sort order
+ccusage daily --order asc       # Show oldest dates first
+ccusage daily --order desc      # Show newest dates first (default)
 ```
 
 `ccusage` is an alias for `ccusage daily`, so you can run it without specifying the subcommand.
 
+### Monthly Report
+
+Shows token usage and costs aggregated by month:
+
+```bash
+# Show all monthly usage
+ccusage monthly
+
+# Filter by date range
+ccusage monthly --since 20250101 --until 20250531
+
+# Use custom Claude data directory
+ccusage monthly --path /custom/path/to/.claude
+
+# Output in JSON format
+ccusage monthly --json
+
+# Control cost calculation mode
+ccusage monthly --mode auto       # Use costUSD when available, calculate otherwise (default)
+ccusage monthly --mode calculate  # Always calculate costs from tokens
+ccusage monthly --mode display    # Always show pre-calculated costUSD values
+
+# Control sort order
+ccusage monthly --order asc       # Show oldest months first
+ccusage monthly --order desc      # Show newest months first (default)
+```
+
 ### Session Report
 
 Shows usage grouped by conversation sessions, sorted by cost:
@@ -153,6 +191,10 @@ ccusage session --json
 ccusage session --mode auto       # Use costUSD when available, calculate otherwise (default)
 ccusage session --mode calculate  # Always calculate costs from tokens
 ccusage session --mode display    # Always show pre-calculated costUSD values
+
+# Control sort order
+ccusage session --order asc       # Show oldest sessions first
+ccusage session --order desc      # Show newest sessions first (default)
 ```
 
 ### Options
@@ -164,6 +206,7 @@ All commands support the following options:
 - `-p, --path <path>`: Custom path to Claude data directory (default: `~/.claude`)
 - `-j, --json`: Output results in JSON format instead of table
 - `-m, --mode <mode>`: Cost calculation mode: `auto` (default), `calculate`, or `display`
+- `-o, --order <order>`: Sort order: `desc` (newest first, default) or `asc` (oldest first).
 - `-d, --debug`: Show pricing mismatch information for debugging
 - `--debug-samples <number>`: Number of sample discrepancies to show in debug output (default: 5)
 - `-h, --help`: Display help message
@@ -175,6 +218,68 @@ All commands support the following options:
 - **`calculate`**: Always calculates costs from token counts using model pricing, ignores any pre-calculated `costUSD` values
 - **`display`**: Always uses pre-calculated `costUSD` values only, shows $0.00 for entries without pre-calculated costs
 
+### MCP (Model Context Protocol) Support
+
+Exposes usage data through Model Context Protocol for integration with other tools:
+
+```bash
+# Start MCP server with stdio transport (for local integration)
+ccusage mcp
+
+# Start MCP server with HTTP stream transport (for remote access)
+ccusage mcp --type http --port 8080
+
+# Control cost calculation mode
+ccusage mcp --mode calculate
+```
+
+The MCP server supports both **stdio** and **HTTP stream** transports:
+- **stdio** (default): Best for local integration where the client directly spawns the process
+- **HTTP stream**: Best for remote access when you need to call the server from another machine or network location
+
+Available MCP tools:
+- `daily`: Returns daily usage reports (accepts `since`, `until`, `mode` parameters)
+- `session`: Returns session usage reports (accepts `since`, `until`, `mode` parameters)
+
+#### Claude Desktop Configuration Example
+
+<div align="center">
+  <img src="https://github.com/ryoppippi/ccusage/blob/main/docs/mcp-claude-desktop.avif?raw=true">
+</div>
+
+To use ccusage MCP with Claude Desktop, add this to your Claude Desktop configuration file:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "ccusage": {
+      "command": "npx",
+      "args": ["ccusage@latest", "mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+Or if you have ccusage installed globally:
+
+```json
+{
+  "mcpServers": {
+    "ccusage": {
+      "command": "ccusage",
+      "args": ["mcp"],
+      "env": {}
+    }
+  }
+}
+```
+
+After adding this configuration, restart Claude Desktop. You'll then be able to use the ccusage tools within Claude to analyze your usage data.
+
 ## Output Example
 
 ### Daily Report

package/dist/arktype-C-GObzDh-Dj1DVoqC.js

@@ -0,0 +1,5 @@
+//#region node_modules/xsschema/dist/arktype-C-GObzDh.js
+const getToJsonSchemaFn = async () => (schema) => schema.toJsonSchema();
+
+//#endregion
+export { getToJsonSchemaFn };

package/dist/calculate-cost.d.ts

@@ -1,10 +1,10 @@
-import "./index-Bazt8Nfd.js";
-import "./pricing-fetcher-BqlslEH3.js";
-import { TokenData, TokenTotals } from "./types-BfZ5dOy7.js";
-import { DailyUsage, SessionUsage } from "./data-loader-DtCt7sNl.js";
+import "./index-BurjgCfW.js";
+import "./pricing-fetcher-DygIroMj.js";
+import { TokenData, TokenTotals } from "./types-y1JQzaKZ.js";
+import { DailyUsage, MonthlyUsage, SessionUsage } from "./data-loader-aUOjeZ06.js";
 
 //#region src/calculate-cost.d.ts
-declare function calculateTotals(data: Array<DailyUsage | SessionUsage>): TokenTotals;
+declare function calculateTotals(data: Array<DailyUsage | MonthlyUsage | SessionUsage>): TokenTotals;
 declare function getTotalTokens(tokens: TokenData): number;
 declare function createTotalsObject(totals: TokenTotals): {
   inputTokens: number;

package/dist/calculate-cost.js

@@ -1,3 +1,3 @@
-import { calculateTotals, createTotalsObject, getTotalTokens } from "./calculate-cost-BnufbprY.js";
+import { calculateTotals, createTotalsObject, getTotalTokens } from "./calculate-cost-2IwHSzmi.js";
 
 export { calculateTotals, createTotalsObject, getTotalTokens };