# Strava Cardio MCP

A local, read-only Model Context Protocol server that connects agents directly to the [official Strava API](https://developers.strava.com/docs/). It gives Codex and other MCP hosts structured access to personal cardio history without putting Strava secrets in chat or project files.

It can read activity summaries, laps, heart-rate and power zones, detailed streams, and aggregate run/ride/swim statistics. Its cardio summary filters strength and climbing by default and flags likely duplicate device imports without silently deleting them.

The server has no create, edit, upload, or delete tools.

## Quick start: Codex on macOS

Requirements: Node.js 20 or newer, Git, Codex CLI, and a Strava account.

```sh
git clone https://github.com/andywangyzfh/strava-mcp.git
cd strava-mcp
npm ci
npm run build
npm run connect
npm run install:codex
```

Before `npm run connect`, create a personal application in [Strava API settings](https://www.strava.com/settings/api) and set **Authorization Callback Domain** to `localhost`. The setup page saves the Client ID, Client Secret, and rotating refresh token in macOS Keychain. Restart Codex or open a new task after registration.

## Linux, Windows, and other MCP hosts

The server also supports a private JSON credentials file outside the repository. Set `STRAVA_MCP_CREDENTIALS_FILE` to an absolute path before running `npm run connect`; the setup helper creates the file with user-only permissions and keeps its rotating refresh token current.

See [docs/SETUP.md](docs/SETUP.md) for macOS Keychain, Linux, Windows PowerShell, manual MCP configuration, OAuth, heart-rate permissions, and troubleshooting.

## Tools

| Tool | Purpose |
| --- | --- |
| `strava_get_athlete` | Authenticated athlete profile |
| `strava_list_activities` | Paginated activity summaries |
| `strava_get_activity` | One detailed activity |
| `strava_get_activity_laps` | Activity laps |
| `strava_get_activity_streams` | Selected time-series streams, downsampled by default |
| `strava_get_athlete_zones` | Heart-rate and power zones |
| `strava_get_athlete_stats` | Aggregate run, ride, and swim statistics |
| `strava_summarize_cardio` | Date-range cardio totals and likely duplicate flags |

Pass Strava athlete and activity IDs as strings so 64-bit values stay exact. See [docs/TOOLS.md](docs/TOOLS.md) for usage guidance.

## Privacy and behavior

- OAuth requests `read` and `activity:read_all` so private activities can be analyzed.
- Access tokens stay in memory. Rotated refresh tokens are persisted to the configured secret store.
- Requests are fixed to Strava's official v3 API and reject HTTP redirects.
- Detailed streams default to at most 2,000 samples and can return up to 10,000.
- The package is marked private to prevent accidental npm publication; the source is MIT licensed.

Read [SECURITY.md](SECURITY.md) before changing credential handling. A ready-made English and Chinese installation prompt for another agent is in [docs/AGENT_INSTALL_PROMPT.md](docs/AGENT_INSTALL_PROMPT.md).

## Development

```sh
npm ci
npm run check
npm test
npm run build
```

## 中文说明

这是一个只读的本地 Strava MCP server，直接使用官方 API，不依赖第三方代理。它可以让 Codex 等 agent 分析跑步、骑行、步行、划船等有氧记录，并读取配速、心率、功率、踏频、海拔、分段和详细时间序列。

macOS 可以使用系统钥匙串保存凭证；Linux 和 Windows 可以使用仓库外的私密 JSON 文件。每位使用者应创建并授权自己的 Strava API application，不要分享 Client Secret 或 refresh token。