内容
# Strava MCP 服务器
一款连接 AI 代理到 [Strava API v3](https://developers.strava.com/docs/reference/) 的 MCP（模型上下文协议）服务器。 使用 TypeScript 构建，通过 stdio 通信。
这允许任何兼容 MCP 的客户端（Claude Desktop、OpenCode 等）通过自然语言获取您的 Strava 活动、流数据、路线、统计数据等。
## 工具列表
| 工具 | 描述 |
|------|-------------|
| `list_activities` | 列出最近的活动，包括距离、时间、海拔、速度和心率 |
| `get_activity` | 获取活动的完整详情，包括分段、圈数、路段努力、装备和卡路里 |
| `get_activity_streams` | 获取活动的原始时间序列数据（心率、海拔、踏频、功率、速度、GPS） |
| `get_activity_zones` | 获取心率和功率区分布 |
| `get_route` | 获取活动的 GPS 路线，以坐标数组或 GeoJSON 格式返回 |
| `get_athlete` | 获取认证运动员的个人资料 |
| `get_athlete_stats` | 获取所有时间和最近的骑行/跑步/游泳统计数据 |
## 前置条件
- Node.js 20+
- 一个 Strava API 应用程序（[在这里创建](https://www.strava.com/settings/api)）
- 一个访问令牌（和可选的刷新令牌凭证）
### 获取 Strava 令牌
1. 在 https://www.strava.com/settings/api 创建一个应用程序
2. 记录您的 **客户端 ID** 和 **客户端密钥**
3. 授权您的应用程序以获取访问令牌和刷新令牌。最快捷的方式：
```bash
https://www.strava.com/oauth/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=http://localhost&scope=read_all,activity:read_all,profile:read_all
```
4. 授权后，从重定向 URL 中获取 `code` 参数并交换：
```bash
curl -X POST https://www.strava.com/oauth/token \
-d client_id=YOUR_CLIENT_ID \
-d client_secret=YOUR_CLIENT_SECRET \
-d code=AUTHORIZATION_CODE \
-d grant_type=authorization_code
```
这将返回 `access_token`、`refresh_token` 和 `expires_at`。
## 设置
```bash
git clone https://github.com/JohanBellander/StravaMCP.git
cd StravaMCP
npm install
npm run build
```
## 环境变量
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `STRAVA_ACCESS_TOKEN` | 是* | Strava API 请求的 Bearer 令牌 |
| `STRAVA_CLIENT_ID` | 否 | OAuth2 客户端 ID（启用自动刷新） |
| `STRAVA_CLIENT_SECRET` | 否 | OAuth2 客户端密钥（启用自动刷新） |
| `STRAVA_REFRESH_TOKEN` | 否 | OAuth2 刷新令牌（启用自动刷新） |
\* 如果您提供所有三个 OAuth 凭证（`CLIENT_ID`、`CLIENT_SECRET`、`REFRESH_TOKEN`），则访问令牌将在过期时自动刷新。在这种情况下，您可以完全省略 `STRAVA_ACCESS_TOKEN`。
## 使用
### 与 OpenCode 配合使用
添加到您的 `opencode.json`：
```json
{
"mcp": {
"strava": {
"type": "local",
"command": ["node", "/path/to/StravaMCP/dist/index.js"],
"environment": {
"STRAVA_ACCESS_TOKEN": "{env:STRAVA_ACCESS_TOKEN}",
"STRAVA_CLIENT_ID": "{env:STRAVA_CLIENT_ID}",
"STRAVA_CLIENT_SECRET": "{env:STRAVA_CLIENT_SECRET}",
"STRAVA_REFRESH_TOKEN": "{env:STRAVA_REFRESH_TOKEN}"
}
}
}
}
```
### 与 Claude Desktop 配合使用
添加到您的 Claude Desktop 配置文件（`~/Library/Application Support/Claude/claude_desktop_config.json` 在 macOS 上）：
```json
{
"mcpServers": {
"strava": {
"command": "node",
"args": ["/path/to/StravaMCP/dist/index.js"],
"env": {
"STRAVA_ACCESS_TOKEN": "your-token-here",
"STRAVA_CLIENT_ID": "your-client-id",
"STRAVA_CLIENT_SECRET": "your-client-secret",
"STRAVA_REFRESH_TOKEN": "your-refresh-token"
}
}
}
}
```
### 直接使用
```bash
export STRAVA_ACCESS_TOKEN=your-token-here
node dist/index.js
```
## 工具详情
### list_activities
列出认证运动员的活动。
**参数：**
- `page`（数字，默认：1）— 页码
- `per_page`（数字，默认：30，最大：200）— 每页活动数
- `after`（数字）— 时间戳，仅返回此时间之后的活动
- `before`（数字）— 时间戳，仅返回此时间之前的活动
**返回：** 活动摘要，包括 id、名称、类型、运动类型、开始日期、距离（公里）、移动时间（小时：分钟：秒）、总时间、海拔增益（米）、平均/最大速度（公里/小时）、平均/最大心率、劳累评分。
### get_activity
获取单个活动的完整详情。
**参数：**
- `id`（数字，必填）— 活动 ID
**返回：** `list_activities` 中的所有内容，以及分段（度量）、圈数、路段努力（名称、时间、距离、个人最佳排名）、装备、卡路里、描述、主观感觉。
### get_activity_streams
获取活动的原始时间序列流数据。
**参数：**
- `id`（数字，必填）— 活动 ID
- `stream_types`（字符串数组，默认：`["time", "distance", "heartrate", "altitude", "cadence", "watts", "velocity_smooth", "latlng"]`）
**返回：** 按类型键控的流数据，每个数据都有一个数据数组和分辨率。
### get_activity_zones
获取心率和功率区分布。
**参数：**
- `id`（数字，必填）— 活动 ID
**返回：** 区分布，包括时间分区明细。
### get_route
获取活动的 GPS 路线，以解码的坐标返回。
**参数：**
- `id`（数字，必填）— 活动 ID
- `format`（`"summary"` 或 `"geojson"`，默认：`"summary"`）
**返回：**
- `summary`：解码的 summary polyline 的 `{lat, lng}` 坐标数组
- `geojson`：具有 LineString 几何图形的 GeoJSON FeatureCollection（全分辨率 polyline）
### get_athlete
获取认证运动员的个人资料。无参数。
**返回：** id、名称、城市、州、国家、性别、体重、FTP、日期偏好、度量偏好。
### get_athlete_stats
获取所有时间和最近的活动统计数据。
**参数：**
- `id`（数字，必填）— 运动员的 Strava ID
**返回：** 最近、今年至今和所有时间的骑行、跑步和游泳总数（次数、距离、移动时间、海拔增益）。还包括最大骑行距离和最大爬坡海拔。
## 速率限制
Strava 强制执行 **每 15 分钟 100 次请求** 和 **每天 1,000 次请求**。服务器通过 `X-RateLimit-Limit` 和 `X-RateLimit-Usage` 响应头跟踪使用情况，并在使用量超过任一限制的 80% 时，在工具响应中包含警告。如果您达到限制，您将收到明确的错误消息，包含当前使用情况和限制。
## 项目结构
```
src/
index.ts # MCP 服务器设置、工具注册、stdio 传输
strava-client.ts # HTTP 客户端、OAuth2 令牌刷新、速率限制跟踪
tools/
list-activities.ts
get-activity.ts
get-activity-streams.ts
get-activity-zones.ts
get-route.ts
get-athlete.ts
get-athlete-stats.ts
utils/
polyline.ts # Google 编码 polyline 解码器
formatting.ts # 单位转换和时间格式化
```
## 开发
```bash
npm run dev # 监视模式 — 在更改时重新编译
npm run build # 一次性构建
npm start # 运行服务器
```
## 许可证
MIT
