Claude Stats MCP - AI 使用统计分析工具
基于 MCP (Model Context Protocol) 的 Claude Code 使用统计分析工具。提供 Node.js 和 Python 两种实现方式。
🚀 快速启动（推荐）
启动 Node.js 版本
特点：
启动 Python 版本
特点：
✅ 自动检查 Python 环境
✅ 自动创建虚拟环境
✅ 自动安装依赖
✅ 支持 STDIO 和 HTTP 两种模式
✅ 适合远程部署
启动后可选择：
STDIO 模式 - 本地使用，配合 Cursor
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 工具并返回结果]
📖 详细文档
🐛 故障排查
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
📚 相关链接
🤝 贡献
欢迎提交 Issue 和 Pull Request！
📄 License
MIT
开发愉快！ 🚀
有问题？查看快速开始指南或各 Demo 的 README！
