Claude Stats MCP - AI 使用统计分析工具

基于 MCP (Model Context Protocol) 的 Claude Code 使用统计分析工具。提供 Node.js 和 Python 两种实现方式。

🚀 快速启动（推荐）

启动 Node.js 版本

./start-node.sh

特点：

• ✅ 自动检查 Node.js 环境
• ✅ 自动安装依赖
• ✅ 适合本地开发
• ✅ STDIO 模式，可直接在 Cursor 中配置

启动 Python 版本

./start-python.sh

特点：

• ✅ 自动检查 Python 环境
• ✅ 自动创建虚拟环境
• ✅ 自动安装依赖
• ✅ 支持 STDIO 和 HTTP 两种模式
• ✅ 适合远程部署

启动后可选择：

1. STDIO 模式 - 本地使用，配合 Cursor
2. HTTP 模式 - 远程访问，地址: http://localhost:8000/mcp

📦 NPX/PIPX 快速使用（推荐分发）

Node.js 版本（NPX）：

# 发布到 npm
./publish-npm.sh

# 用户使用
npx claude-stats-mcp

Python 版本（PIPX）：

# 发布到 PyPI
./publish-pypi.sh

# 用户使用
pipx install claude-stats-mcp

详细说明: 查看 使用指南.md

📁 项目结构

ai-mcp-study/
├── start-node.sh           # Node.js 快速启动脚本 ⭐
├── start-python.sh         # Python 快速启动脚本 ⭐
├── publish-npm.sh          # NPM 包发布脚本 📦
├── publish-pypi.sh         # PyPI 包发布脚本 🐍
├── keys.json               # API Key 配置文件
├── node-mcp-demo/          # Node.js 实现
│   ├── src/
│   │   ├── index.ts        # MCP 服务器入口
│   │   ├── tools.ts        # 8个工具函数
│   │   └── utils/          # 工具模块
│   └── package.json
├── python-mcp-demo/        # Python 实现
│   ├── server.py           # MCP 服务器 + 工具
│   ├── utils/              # 工具模块
│   └── requirements.txt
└── 快速开始.md             # 详细教程

🛠️ 在 Cursor 中配置

Node.js 版本配置

编辑 ~/.cursor/mcp.json 或 ~/.config/cursor/config.json:

{
  "mcpServers": {
    "claude-stats-node": {
      "command": "npx",
      "args": ["tsx", "/完整路径/node-mcp-demo/src/index.ts"],
      "env": {
        "KEYS_CONFIG_PATH": "/完整路径/keys.json"
      }
    }
  }
}

Python 版本配置

STDIO 模式（本地）

{
  "mcpServers": {
    "claude-stats-python": {
      "command": "/完整路径/python-mcp-demo/venv/bin/python",
      "args": ["/完整路径/python-mcp-demo/server.py"],
      "env": {
        "KEYS_CONFIG_PATH": "/完整路径/keys.json"
      }
    }
  }
}

HTTP 模式（远程）

{
  "mcpServers": {
    "claude-stats-python": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

🔧 8个可用工具

工具名称	功能描述	示例问题
query_today_stats	查询今日统计	"今天总共花了多少钱？"
query_monthly_stats	查询本月统计	"本月使用情况怎么样？"
query_user_stats	查询特定用户	"查询江俊锋的使用情况"
query_top_users	Top用户排行	"使用率最高的是谁？"
compare_users	对比用户	"对比江俊锋和陈雷"
analyze_usage_trend	趋势分析	"分析使用趋势"
detect_anomalies	异常检测	"有没有超出限额的？"
generate_report	生成报告	"生成今日报告"

✅ 快速验证

启动服务后，在 Cursor 中重启，然后尝试：

你: 今天使用率最高的是谁？
AI: [会自动调用 query_top_users 工具并返回结果]

📖 详细文档

• 快速开始指南 - 5分钟快速体验
• 使用指南 - ⭐ NPX/PIPX 完整使用说明
• MCP开发入门与实战 - 完整教程
• 部署指南 - 生产环境部署
• Node.js Demo 文档 - Node.js 版详细说明
• Python Demo 文档 - Python 版详细说明

🐛 故障排查

Node.js 脚本问题

# 检查 Node 版本（需要 >= 18）
node -v

# 手动清理重装
cd node-mcp-demo
rm -rf node_modules package-lock.json
npm install

Python 脚本问题

# 检查 Python 版本（需要 >= 3.8）
python3 --version

# 手动重建虚拟环境
cd python-mcp-demo
rm -rf venv
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

配置文件问题

确保 keys.json 文件存在且格式正确：

{
  "api_keys": [
    {
      "name": "用户名",
      "account": "账号标识",
      "apiKey": "cr_xxxxx"
    }
  ]
}

🔄 手动启动（不使用脚本）

Node.js

cd node-mcp-demo
npm install
export KEYS_CONFIG_PATH=/完整路径/keys.json
npm run dev

Python

cd python-mcp-demo
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# STDIO 模式
KEYS_CONFIG_PATH=/完整路径/keys.json python server.py

# HTTP 模式
KEYS_CONFIG_PATH=/完整路径/keys.json \
MCP_TRANSPORT=http \
MCP_PORT=8000 \
python server.py

🎯 技术栈

Node.js 版本

• FastMCP (TypeScript)
• Axios
• TypeScript
• Zod (类型验证)

Python 版本

• FastMCP (Python)
• HTTPX
• Pydantic
• python-dotenv

📚 相关链接

• MCP 官方文档
• FastMCP TypeScript
• FastMCP Python
• Cursor MCP 文档

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📄 License

MIT

---

开发愉快！ 🚀

有问题？查看快速开始指南或各 Demo 的 README！