strava-mcp

Strava MCP

一个模型上下文协议（MCP）服务，为官方 Strava MCP 连接器提供补充。它添加了写入访问权限、路段、路线、照片、衍生分析和交互式可视化，这些都是官方连接器不提供的。

功能

• 创建和更新活动（标题、描述、运动类型、装备、标记）
• 为没有设备记录的训练创建手动活动（力量训练、瑜伽、跑步机）
• 探索、查看、加星标和管理路段
• 获取每项活动的照片、区间分析和跑步摘要
• 列出并查看已保存路线的详情
• 导出路线（GPX/TCX）和活动轨迹（根据数据流生成 GPX）
• Strava 未提供的衍生分析：间歇检测、爬升／下降分析、有氧解耦、训练负荷、体能／疲劳／状态（CTL/ATL/TSB），以及针对目标比赛日状态计算出的理想减量训练方案
• 通过 MCP 提供适合 AI 的 JSON 响应
• 九种可在兼容 MCP 的宿主中呈现的交互式可视化——活动图表、步频趋势、路线地图、活动路段、训练负荷、活动对比、活动区间、路段进度和体能趋势
• 用于每周回顾、为跑步添加注释和搜寻路段的引导式提示词（文档）
• 自动刷新令牌
• 适用于远程部署的可流式 HTTP 传输

在在线 Storybook中浏览 UI 组件。

完整的工具目录、提示词、权限行为和请求示例请参阅文档。

快速开始（Docker）

1. 创建 Strava API 应用

1. 前往 strava.com/settings/api
2. 创建一个新应用：
   • 填写应用详情（名称、网站、描述）
   • 将“Authorization Callback Domain”设置为你的公开 URL 主机名（例如，strava-mcp.example.com）
   • 记下你的客户端 ID和客户端密钥

2. 配置环境

cp .env.example .env

使用你的值编辑 .env：

STRAVA_CLIENT_ID=your_client_id
STRAVA_CLIENT_SECRET=your_client_secret
PUBLIC_URL=https://your-public-url.example.com

所有变量都列在 docs/operations.md 中。想使用预构建镜像？拉取 ghcr.io/ljcl/strava-mcp:latest（也可在 MCP 注册表中找到，名称为 io.github.ljcl/strava-mcp），并将 compose 配置中的 image: 指向它，而不是自行构建；你仍需自行提供 Strava 凭据。已发布的镜像附带 SBOM／来源证明，可供验证——请参阅 operations.md。

**关于 ./data 绑定挂载的说明：**令牌会保存在该目录中，而 distroless 镜像以非 root UID 65534 运行，因此该 UID 必须能够写入此目录，否则首次运行时令牌持久化会失败：

mkdir -p data
sudo chown -R 65534:65534 data

也可以在 docker-compose.yml 中使用命名卷（例如 strava-data:/app/data），Docker 会以正确的所有权初始化该卷。更多详情请参阅 operations.md。

3. 启动服务

docker compose up -d

GET /health 会报告服务是否存活，且不会消耗 Strava API 请求；设置 MCP_AUTH_TOKEN 后，它还会报告身份验证和速率限制状态。响应格式和监控指南请参阅：operations.md。

4. 使用 Strava 授权

在浏览器中访问 https://your-public-url/auth/start。授权后，令牌会自动保存，此后也会自动刷新。可随时在 /auth/status 查看状态。

如果设置了 MCP_AUTH_TOKEN，请在两个 URL 后都添加 ?token=<MCP_AUTH_TOKEN>。

5. 连接到 Claude Desktop

添加到 Claude 配置文件（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "strava": {
      "type": "url",
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

只有设置了 MCP_AUTH_TOKEN 时才需要 headers 条目（建议用于通过隧道暴露的服务 — 请参阅保护端点）。

重启 Claude Desktop 以加载新配置。

连接到 AI 工具

大多数 AI 工具（Claude Desktop、Claude Code 等）都需要 HTTPS URL 才能访问 MCP 服务。由于服务运行在本地网络上，你需要使用隧道将其暴露出来。

Tailscale Funnel（推荐）

Tailscale Funnel 无需配置，即可通过 HTTPS 将本地端口暴露到互联网：

tailscale funnel --bg 3000
# → https://your-machine.tail1234.ts.net

在 .env 中将 PUBLIC_URL 设置为生成的 URL。

Cloudflare Tunnel

cloudflared tunnel --url http://localhost:3000

保护端点

隧道会让任何发现 URL 的人都能访问 /mcp，包括 update-activity 写入工具。将 MCP_AUTH_TOKEN 设置为较长的随机密钥（openssl rand -hex 32），这样每个 /mcp 请求都需要 Authorization: Bearer <token>；下方每个客户端代码片段都展示了应在何处添加请求头。该密钥也会保护 /auth/start 和 /auth/status。完整详情（包括如何确保 OAuth 回调安全）：operations.md。

在 .env 中与 Strava 凭据一起设置该密钥 — docker-compose.yml 会自动传递它。

AI Tool (Claude Desktop, Claude Code, etc.)
    │  HTTPS
HTTPS Tunnel (Tailscale / Cloudflare)
    │  HTTP (localhost:3000)
Strava MCP Server (Docker / Bun)
    │  HTTPS
Strava API

客户端配置

该服务适用于任何支持 Streamable HTTP 传输的 MCP 客户端。在下方每个代码片段中，将 https://your-public-url 替换为你的隧道 URL（本地开发时则替换为 http://localhost:3000），并且仅在设置了 MCP_AUTH_TOKEN 时添加 Authorization 请求头。

Claude Code

claude mcp add --transport http strava https://your-public-url/mcp \
  --header "Authorization: Bearer your-mcp-auth-token"

Cursor

将配置添加到项目中的 .cursor/mcp.json（或添加到所有项目共用的 ~/.cursor/mcp.json）：

{
  "mcpServers": {
    "strava": {
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

VS Code

将配置添加到工作区中的 .vscode/mcp.json（或从命令面板运行 MCP: Add Server）：

{
  "servers": {
    "strava": {
      "type": "http",
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

其他客户端（通用 Streamable HTTP）

任何支持 Streamable HTTP 的客户端都可以直接连接到 /mcp 端点。一个 URL 同时支持两个协议版本：2026-07-28 客户端会发送携带 io.modelcontextprotocol/* 信封键的无状态请求（server/discover 会公布功能）；2025 年版客户端则使用常规的 initialize 握手。发送 POST JSON-RPC 消息时，请带上 Accept: application/json, text/event-stream 请求头。协议详情：docs/architecture.md。

与官方 Strava MCP 一起使用

Strava 官方 MCP 连接器负责发现活动和基本读取。此服务则补充了官方连接器不支持的所有功能：写入活动、片段、路线，以及导出 GPX/TCX、照片、衍生分析和交互式可视化。

同时安装两者

• 官方：claude mcp add --transport http strava-mcp https://mcp.strava.com/mcp（或通过 claude.ai Connectors / Claude Desktop 安装）。
• 此服务：请参阅上方的安装步骤。

功能分工

功能	官方	此服务
列出 / 读取活动、数据流、个人资料、区域、装备、俱乐部、训练计划	是	否（使用官方连接器）
更新活动、收藏片段	否	是
片段详情 / 搜索 / 努力记录	否	是
路线及 GPX/TCX 导出	否	是
活动 GPX 导出（由数据流合成）	否	是
活动照片	否	是
运动员统计数据、单项活动区域、最佳努力记录、跑步摘要、训练负荷、对比	否	是
间歇、爬坡和有氧分析；体能/疲劳/状态（CTL/ATL/TSB）	否	是
交互式应用：活动图表、步频趋势、路线地图、活动片段、训练负荷、活动对比、活动区域、片段进度、体能趋势	否	是

注意事项

• 官方连接器需要 Strava 订阅，目前仅在 Anthropic 客户端中运行。
• 移除重复读取后，此服务现在实际上假设已安装官方连接器，用于发现活动。聚合分析工具（get-best-efforts、get-training-load）会获取自己的活动列表，但单项活动工具（get-running-summary、compare-activities、get-activity-zones 等）需要从官方 list_activities 获取活动 ID。
• 两者使用独立的速率限制配额，因此同时运行可以分散 API 负载。

推荐工作流

使用官方连接器发现并读取活动，然后使用此服务进行写入、探索路段、管理和导出路线，以及可视化。模型可以将官方 list_activities 返回的活动 ID 直接传递给此服务的工具。

示例请求

可以向 AI 助手提出以下问题（使用官方 Strava MCP 发现活动 ID，然后将其传递给这些工具）：

• “将活动 12345678 的标题更新为‘晨间阈值跑’”
• “显示活动 12345678 的心率区间分布”
• “分析活动 12345678 中的间歇跑——每组重复跑的表现有没有下滑？”
• “我周日的长跑是前快后慢，还是只是因为爬坡？”
• “我的比赛在 9 月 13 日——接下来三周应该怎么安排，才能让比赛时的 TSB 达到 +10？”
• “我在路段 8109834 上有变快吗？显示我的跑步记录历史”
• “绘制我的比赛路线，在 10 公里、21 公里和 32 公里处标出补给点，并标记 28 公里处的爬坡”

更多内容请见 docs/tools.md。

本地开发

先决条件：Bun 和 Strava 帐户。

bun install

# Guided OAuth flow using localhost as redirect URI
cd apps/server && bun run setup-auth && cd ../..

# Start dev server (server + MCP App watchers)
bun run dev

然后将任意客户端指向 http://localhost:3000/mcp。仓库布局、任务运行器、测试、覆盖率门槛和 Storybook 工作流详见 docs/development.md。Agent 约定见 AGENTS.md。

文档

文档	内容
docs/tools.md	完整工具目录、提示词、权限行为、示例请求
docs/operations.md	环境变量、身份验证/令牌处理、健康检查端点、速率限制、端点安全
docs/architecture.md	服务架构：传输、HTTP 层、缓存、错误分类、分析计算
docs/mcp-apps.md	MCP App 软件包：共享外壳、移动端、主题设置、各应用详情
docs/development.md	Monorepo 机制：Turborepo、覆盖率门槛、Storybook 门槛、Docker 构建
docs/releasing.md	发布自动化：Conventional Commit PR 标题、release-please、发布
docs/project.md	问题跟踪和项目看板

PR 会通过 squash 合并，且 PR 标题会成为 main 上的提交信息，因此请按 Conventional Commit 规范编写（feat: 次要版本、fix: 补丁版本、feat!: 主要版本；chore:/docs:/refactor:/ci: 不会触发发布）。CI 检查会拒绝不符合规范的标题；详情请见 docs/releasing.md。

故障排除

AI 工具无法连接到服务 — MCP 要求使用 HTTPS URL。使用隧道（Tailscale Funnel 或 Cloudflare Tunnel）公开本地服务。请参阅连接到 AI 工具。

OAuth 回调失败 — 确保 .env 中的 PUBLIC_URL 与隧道 URL 完全一致，并且在 Strava API 设置中将相同的主机名设为“Authorization Callback Domain”。

令牌错误或令牌已过期 — 先检查 /health：authenticated 和 token_expires_at 可以告诉你服务是否持有可用令牌，从而区分身份验证问题和连接问题。然后访问 /auth/start 重新授权。令牌会自动刷新，但如果刷新令牌已被撤销，或新版本新增了作用域，则需要完整重新授权。请参阅 operations.md。

服务是否正在运行且可以连接？ — 运行 curl https://your-public-url/health。此请求不会访问 Strava API，因此即使速率限制已用尽，也能正常工作。

容器重启后令牌无法保留（Docker） — 容器以非 root UID 65534 运行，因此 ./data 绑定挂载必须允许该 UID 写入（sudo chown -R 65534:65534 data），或者改用命名卷。请参阅快速入门步骤 2和 operations.md。

授予读取工具权限后，客户端仍会再次提示授权 — 某个版本可能重命名了工具或更改了其输入架构；授权按工具标识存储，因此会丢失。版本发布说明会对此进行说明。否则，权限持久化由客户端负责——请检查连接器级和单个工具的设置。请参阅 docs/tools.md。

许可证

MIT