项目简介

'ccusage' 不仅是一个强大的Claude Code使用量分析CLI工具，它还包含一个完整的Model Context Protocol (MCP) 服务器实现。这个MCP服务器能够以标准化的方式，将本地存储的Claude Code使用数据（如每日、每月、会话和计费周期报告）通过JSON-RPC协议提供给兼容的LLM客户端。它支持Stdio和HTTP/SSE两种传输协议，方便与各种MCP客户端（如Claude Desktop）进行集成，实现成本监控和上下文数据查询。

主要功能点

令牌用量分析： 提供Claude Code的输入、输出、缓存创建和缓存读取令牌的详细使用量。
成本追踪： 自动计算并显示基于LiteLLM定价数据的令牌使用成本（美元），支持从Claude Code自带数据或实时计算。
多种报告类型： 提供每日、每月、会话（按对话）和5小时计费窗口（区块）的聚合报告。
工具化数据访问： 将不同的报告功能封装为MCP工具，允许LLM客户端按需调用，获取结构化数据。
灵活的传输协议： 支持通过标准输入/输出（Stdio）或HTTP/SSE进行通信，以适应不同的客户端集成场景。
会话和项目管理： 能够识别和管理不同对话会话和项目的使用数据。

安装步骤

'ccusage' 工具可以通过'npm'、'bun'或'deno'快速运行其CLI命令，而MCP服务器部分则作为一个单独的包 '@ccusage/mcp' 提供。

1. 运行MCP服务器（推荐使用 'bunx'）： 这将直接下载并运行MCP服务器：

bunx @ccusage/mcp@latest

或者使用 'npx'：

npx @ccusage/mcp@latest

2. （可选）全局安装： 如果您希望全局安装，可以：

npm install -g ccusage @ccusage/mcp
# 然后运行MCP服务器
ccusage mcp

服务器配置

MCP客户端需要配置MCP服务器的连接信息，通常是一个JSON文件。以下是'ccusage' MCP服务器的两种常见配置示例（Stdio和HTTP传输），您可以根据您的MCP客户端的需要进行选择和调整。

Stdio传输配置示例

此配置通过标准输入/输出来与服务器通信。

{
  "name": "Claude用量分析服务 (Stdio)",
  "description": "通过标准输入/输出（Stdio）传输协议为LLM客户端提供Claude Code令牌使用量和成本的详细分析报告。",
  "server": {
    "command": "bunx",
    "args": [
      "@ccusage/mcp@latest",
      "--type",
      "stdio"
    ],
    "transport": "stdio",
    "capabilities": {
      "structuredContent": true
    }
  },
  "tools": [
    {
      "name": "daily",
      "description": "获取每日Claude Code令牌使用量和成本报告。",
      "input_schema": {
        "type": "object",
        "properties": {
          "since": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选起始日期，格式为 YYYYMMDD。" },
          "until": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选结束日期，格式为 YYYYMMDD。" },
          "mode": { "type": "string", "enum": ["auto", "calculate", "display"], "default": "auto", "description": "成本计算模式：'auto'（优先使用预计算成本，否则计算），'calculate'（总是计算），'display'（总是使用预计算成本）。" },
          "timezone": { "type": "string", "description": "报告的时区，例如 'UTC', 'America/New_York', 'Asia/Tokyo'。" },
          "locale": { "type": "string", "default": "en-CA", "description": "日期/时间格式化使用的区域设置，例如 'en-US', 'ja-JP', 'de-DE' (默认: en-CA)。" }
        }
      }
    },
    {
      "name": "monthly",
      "description": "获取每月Claude Code令牌使用量和成本报告。",
      "input_schema": {
        "type": "object",
        "properties": {
          "since": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选起始日期，格式为 YYYYMMDD。" },
          "until": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选结束日期，格式为 YYYYMMDD。" },
          "mode": { "type": "string", "enum": ["auto", "calculate", "display"], "default": "auto", "description": "成本计算模式。" },
          "timezone": { "type": "string", "description": "报告的时区。" },
          "locale": { "type": "string", "default": "en-CA", "description": "日期/时间格式化使用的区域设置 (默认: en-CA)。" }
        }
      }
    },
    {
      "name": "session",
      "description": "获取按对话会话分组的Claude Code令牌使用量和成本报告。",
      "input_schema": {
        "type": "object",
        "properties": {
          "since": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选起始日期，格式为 YYYYMMDD。" },
          "until": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选结束日期，格式为 YYYYMMDD。" },
          "mode": { "type": "string", "enum": ["auto", "calculate", "display"], "default": "auto", "description": "成本计算模式。" },
          "timezone": { "type": "string", "description": "报告的时区。" },
          "locale": { "type": "string", "default": "en-CA", "description": "日期/时间格式化使用的区域设置 (默认: en-CA)。" }
        }
      }
    },
    {
      "name": "blocks",
      "description": "获取按5小时计费区块分组的Claude Code令牌使用量和成本报告。",
      "input_schema": {
        "type": "object",
        "properties": {
          "since": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选起始日期，格式为 YYYYMMDD。" },
          "until": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选结束日期，格式为 YYYYMMDD。" },
          "mode": { "type": "string", "enum": ["auto", "calculate", "display"], "default": "auto", "description": "成本计算模式。" },
          "timezone": { "type": "string", "description": "报告的时区。" },
          "locale": { "type": "string", "default": "en-CA", "description": "日期/时间格式化使用的区域设置 (默认: en-CA)。" }
        }
      }
    }
  ]
}

HTTP传输配置示例

此配置通过HTTP/SSE协议进行通信，服务器将监听指定端口。

{
  "name": "Claude用量分析服务 (HTTP)",
  "description": "通过HTTP/SSE传输协议为LLM客户端提供Claude Code令牌使用量和成本的详细分析报告，服务器监听指定端口。",
  "server": {
    "command": "bunx",
    "args": [
      "@ccusage/mcp@latest",
      "--type",
      "http",
      "--port",
      "8080"
    ],
    "transport": "http",
    "capabilities": {
      "structuredContent": true
    }
  },
  "tools": [
    {
      "name": "daily",
      "description": "获取每日Claude Code令牌使用量和成本报告。",
      "input_schema": {
        "type": "object",
        "properties": {
          "since": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选起始日期，格式为 YYYYMMDD。" },
          "until": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选结束日期，格式为 YYYYMMDD。" },
          "mode": { "type": "string", "enum": ["auto", "calculate", "display"], "default": "auto", "description": "成本计算模式。" },
          "timezone": { "type": "string", "description": "报告的时区。" },
          "locale": { "type": "string", "default": "en-CA", "description": "日期/时间格式化使用的区域设置 (默认: en-CA)。" }
        }
      }
    },
    {
      "name": "monthly",
      "description": "获取每月Claude Code令牌使用量和成本报告。",
      "input_schema": {
        "type": "object",
        "properties": {
          "since": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选起始日期，格式为 YYYYMMDD。" },
          "until": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选结束日期，格式为 YYYYMMDD。" },
          "mode": { "type": "string", "enum": ["auto", "calculate", "display"], "default": "auto", "description": "成本计算模式。" },
          "timezone": { "type": "string", "description": "报告的时区。" },
          "locale": { "type": "string", "default": "en-CA", "description": "日期/时间格式化使用的区域设置 (默认: en-CA)。" }
        }
      }
    },
    {
      "name": "session",
      "description": "获取按对话会话分组的Claude Code令牌使用量和成本报告。",
      "input_schema": {
        "type": "object",
        "properties": {
          "since": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选起始日期，格式为 YYYYMMDD。" },
          "until": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选结束日期，格式为 YYYYMMDD。" },
          "mode": { "type": "string", "enum": ["auto", "calculate", "display"], "default": "auto", "description": "成本计算模式。" },
          "timezone": { "type": "string", "description": "报告的时区。" },
          "locale": { "type": "string", "default": "en-CA", "description": "日期/时间格式化使用的区域设置 (默认: en-CA)。" }
        }
      }
    },
    {
      "name": "blocks",
      "description": "获取按5小时计费区块分组的Claude Code令牌使用量和成本报告。",
      "input_schema": {
        "type": "object",
        "properties": {
          "since": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选起始日期，格式为 YYYYMMDD。" },
          "until": { "type": "string", "pattern": "^\\d{8}$", "description": "筛选结束日期，格式为 YYYYMMDD。" },
          "mode": { "type": "string", "enum": ["auto", "calculate", "display"], "default": "auto", "description": "成本计算模式。" },
          "timezone": { "type": "string", "description": "报告的时区。" },
          "locale": { "type": "string", "default": "en-CA", "description": "日期/时间格式化使用的区域设置 (默认: en-CA)。" }
        }
      }
    }
  ]
}

基本使用方法

启动MCP服务器后，它会在后台运行并等待MCP客户端连接。

启动服务器（Stdio模式）： 默认情况下，MCP服务器会以Stdio模式启动：
```
bunx @ccusage/mcp@latest
```
您也可以明确指定 Stdio 模式：
```
bunx @ccusage/mcp@latest --type stdio
```
在此模式下，服务器通过标准输入和输出来与客户端通信。
启动服务器（HTTP模式）： 您也可以指定HTTP模式，并设置端口（例如 '8080'）：
```
bunx @ccusage/mcp@latest --type http --port 8080
```
服务器将在 'http://localhost:8080' 上监听MCP请求。

一旦服务器启动，兼容的MCP客户端即可通过上述配置与其连接，并调用已注册的工具来获取Claude Code的使用数据报告。例如，一个LLM客户端可能会调用 'daily' 工具来获取最近的每日使用量报告。

关键词