# MCP 服务使用指南
本文档介绍如何通过不同方式使用 Claude Stats MCP 服务。
## 📦 四种使用方式对比
| 方式 | 适用场景 | 优点 | 缺点 | 启动命令 |
|-----|---------|------|------|---------|
| **本地启动** | 开发调试 | 最灵活，便于修改 | 需要本地环境 | `./start-node.sh` 或 `./start-python.sh` |
| **NPX（Node.js）** | 快速体验 | 无需安装，一键运行 | 仅 Node.js 版 | `npx claude-stats-mcp` |
| **PIPX（Python）** | 快速体验 | 无需虚拟环境，隔离安装 | 仅 Python 版 | `pipx install claude-stats-mcp` |
| **生产部署** | 正式环境 | 稳定可靠 | 需要服务器 | 见 [DEPLOYMENT.md](./DEPLOYMENT.md) |
---
## 🚀 方式一：本地快速启动（推荐开发）
### Node.js 版本
```bash
# 一键启动
./start-node.sh
```
**特点**：
- ✅ 自动检查环境和依赖
- ✅ 适合本地开发和调试
- ✅ STDIO 模式，直连 Cursor
### Python 版本
```bash
# 一键启动
./start-python.sh
# 选择模式
1) STDIO 模式 - 本地使用
2) HTTP 模式 - 远程访问（http://localhost:8000/mcp）
```
**特点**：
- ✅ 自动创建虚拟环境
- ✅ 支持两种运行模式
- ✅ 适合本地和远程测试
**详细说明**：查看 [快速开始.md](./快速开始.md)
---
## 📦 方式二：NPX 一键运行（Node.js）
### 什么是 NPX？
NPX 是 npm 自带的工具，可以直接运行 npm 包而无需安装。
### 前提条件
1. **发布到 npm**：
```bash
cd node-mcp-demo
../publish-npm.sh
```
2. **等待发布完成**（通常几分钟）
### 使用方式
#### 一次性运行（推荐）
```bash
# 直接运行，无需安装
npx claude-stats-mcp
```
#### 全局安装
```bash
# 全局安装
npm install -g claude-stats-mcp
# 直接运行
claude-stats-mcp
```
### Cursor 配置
**文件位置**：`~/.cursor/mcp.json` 或 `~/.config/cursor/config.json`
```json
{
"mcpServers": {
"claude-stats": {
"command": "npx",
"args": ["-y", "claude-stats-mcp"],
"env": {
"KEYS_CONFIG_PATH": "/path/to/keys.json"
}
}
}
}
```
**注意**：
- `-y` 参数表示自动确认安装
- `KEYS_CONFIG_PATH` 需要使用绝对路径
---
## 🐍 方式三：PIPX 安装（Python）
### 什么是 PIPX？
PIPX 是 Python 版的 NPX，专门用于安装和运行 Python CLI 工具。
### 为什么 Python 不能用 NPX？
- **NPX** 是 npm/Node.js 生态的工具，只能运行 JavaScript 包
- **PIPX** 是 PyPI/Python 生态的工具，用于 Python CLI 工具
- 两者功能类似，但分属不同生态系统
### 安装 PIPX
#### macOS/Linux
```bash
# 使用 pip 安装
python3 -m pip install --user pipx
python3 -m pipx ensurepath
# 或使用 Homebrew（macOS）
brew install pipx
pipx ensurepath
```
#### Windows
```bash
python -m pip install --user pipx
python -m pipx ensurepath
```
### 前提条件
1. **发布到 PyPI**：
```bash
cd python-mcp-demo
../publish-pypi.sh
```
2. **选择 PyPI**（不是 TestPyPI）
### 使用方式
#### 安装
```bash
# 安装包
pipx install claude-stats-mcp
# 查看已安装
pipx list
```
#### 运行
```bash
# 直接运行
claude-stats-mcp
# 或一次性运行（无需安装）
pipx run claude-stats-mcp
```
#### 更新和卸载
```bash
# 更新到最新版本
pipx upgrade claude-stats-mcp
# 卸载
pipx uninstall claude-stats-mcp
```
### Cursor 配置
```json
{
"mcpServers": {
"claude-stats": {
"command": "claude-stats-mcp",
"env": {
"KEYS_CONFIG_PATH": "/path/to/keys.json"
}
}
}
}
```
---
## 🔧 配置说明
### 环境变量
所有方式都需要配置 API Key 文件路径：
```bash
# 环境变量方式
export KEYS_CONFIG_PATH="/path/to/keys.json"
# 或在 Cursor 配置中指定
"env": {
"KEYS_CONFIG_PATH": "/path/to/keys.json"
}
```
### keys.json 格式
```json
{
"api_keys": [
{
"name": "用户名",
"account": "账号标识",
"apiKey": "cr_xxxxx"
}
]
}
```
---
## 🆚 NPX vs PIPX 详细对比
### 相同点
| 特性 | NPX | PIPX |
|-----|-----|------|
| **一键运行** | ✅ | ✅ |
| **无需全局安装** | ✅ | ✅ |
| **环境隔离** | ✅ | ✅ |
| **自动更新** | ✅ | ✅ |
| **适合分发工具** | ✅ | ✅ |
### 不同点
| 特性 | NPX | PIPX |
|-----|-----|------|
| **生态系统** | npm/Node.js | PyPI/Python |
| **包格式** | JavaScript/TypeScript | Python |
| **运行命令** | `npx package` | `pipx install package` |
| **发布平台** | npmjs.com | pypi.org |
| **缓存位置** | npm cache | pipx 目录 |
### 技术原理
**NPX**：
1. 检查本地是否有包
2. 如果没有，临时下载到缓存
3. 运行包的 bin 脚本
4. 执行完可选择保留或删除
**PIPX**：
1. 为每个工具创建独立虚拟环境
2. 在虚拟环境中安装包
3. 创建全局可用的命令链接
4. 完全隔离，避免依赖冲突
---
## 🔍 故障排查
### NPX 问题
#### 1. 包找不到
```bash
# 检查包是否发布成功
npm view claude-stats-mcp
# 手动安装测试
npm install -g claude-stats-mcp
```
#### 2. 权限问题
```bash
# macOS/Linux 使用 sudo
sudo npm install -g claude-stats-mcp
# 或配置 npm 前缀
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH
```
### PIPX 问题
#### 1. pipx 命令找不到
```bash
# 确保 PATH 正确
pipx ensurepath
# 重新加载 shell
source ~/.bashrc # 或 ~/.zshrc
```
#### 2. 包安装失败
```bash
# 使用 pip 直接测试
pip install claude-stats-mcp
# 查看详细错误
pipx install claude-stats-mcp --verbose
```
#### 3. Python 版本问题
```bash
# 检查 Python 版本（需要 >= 3.8）
python3 --version
# 指定 Python 版本
pipx install --python python3.11 claude-stats-mcp
```
### 配置文件问题
#### 1. 路径错误
- ✅ 使用绝对路径：`/Users/mac/Desktop/project/keys.json`
- ❌ 避免相对路径：`./keys.json` 或 `~/keys.json`
#### 2. 权限问题
```bash
# 检查文件权限
ls -l /path/to/keys.json
# 修改权限（如果需要）
chmod 644 /path/to/keys.json
```
---
## 📊 使用场景建议
### 开发阶段
**推荐**：本地启动脚本
- 使用 `./start-node.sh` 或 `./start-python.sh`
- 便于修改代码和调试
- 实时看到效果
### 快速体验
**推荐**：NPX/PIPX
- Node.js 用户：`npx claude-stats-mcp`
- Python 用户：`pipx install claude-stats-mcp`
- 无需克隆代码，一键体验
### 日常使用
**推荐**：全局安装
- Node.js：`npm install -g claude-stats-mcp`
- Python：`pipx install claude-stats-mcp`
- 启动更快，使用更方便
### 团队协作
**推荐**：NPX/PIPX + 文档
- 在 README 中说明使用方式
- 团队成员无需配置环境
- 统一版本，避免差异
### 生产部署
**推荐**：Docker 或服务器部署
- 查看 [DEPLOYMENT.md](./DEPLOYMENT.md)
- 稳定可靠，支持远程访问
- 适合正式环境
---
## 📚 相关文档
- [快速开始指南](./快速开始.md) - 5分钟快速体验
- [MCP开发入门与实战](./MCP开发入门与实战.md) - 完整教程
- [部署指南](./DEPLOYMENT.md) - 生产环境部署
- [Node.js Demo 文档](./node-mcp-demo/README.md) - Node.js 版详细说明
- [Python Demo 文档](./python-mcp-demo/README.md) - Python 版详细说明
---
**选择适合你的方式，开始使用吧！** 🚀
