Strava MCP Bridge

strava-mcp-bridge

无需创建自己的 Strava 开发者应用，即可在 Codex、OpenCode 和其他本地 stdio MCP 客户端中使用 Strava 官方 MCP。

此桥接程序在 Apple Silicon macOS 上本地运行。OAuth 凭据保存在 macOS 钥匙串中，大型活动数据流保存在本地文件中，并且 GPS/位置 数据会在进入 AI 上下文前被拦截。

它能实现什么

连接后，本地编码 Agent 可以将 Strava 数据用于实际项目工作流，而不必依赖复制的摘要或合成数据。

You: Pull my new rides since the local watermark and rebuild my training dashboard.

Codex:
  3 new rides found through the official Strava MCP
  full activity streams saved locally, omitted from model context
  training summary and fitness chart rebuilt
  no GPS, location, or polyline fields returned to the conversation

其他任务示例：

• “比较我本周骑行的心率负荷。”
• “获取此活动中不含位置信息的数据流，并更新我的分析。”
• “使用我最新的骑行数据，刷新此仓库中的 PMC/TRIMP 仪表板。”

此桥接程序提供安全的 Strava 连接。随后，你的 Agent 可以将结果与本地脚本、笔记本、仪表板或训练分析代码结合使用。

为什么开发它

Strava 发布了官方 MCP 连接器，但其文档说明的首次授权流程目前面向 Claude 客户端。Codex 支持 MCP，但目前无法直接完成此 Strava OAuth 初始化流程。

strava-mcp-bridge 弥补了这一缺口：

1. 通过 Claude Code 为官方 Strava MCP 授权一次。
2. 明确运行 strava-mcp-bridge bootstrap。
3. 此桥接程序将已授权的凭据迁移到自己的钥匙串项目中。
4. 它维护轮换刷新令牌链，并将获准的 MCP 请求转发到 https://mcp.strava.com/mcp。
5. 日常使用 Codex/OpenCode 时，不再读取或调用 Claude Code。

这不是 Strava REST API 封装程序，不提供共享凭据，也不会绕过用户授权。

选择合适的方式

方式	是否需要创建自己的 Strava 应用？	凭据保管方式	Strava 接口	主要权衡
Claude 中的官方连接器	否	官方客户端	官方 Strava MCP	如果 Claude 已适合你的工作流，这是最简单的选择
社区自托管 Strava MCP	通常需要	本地	Strava REST API	支持广泛的客户端，但应用和 OAuth 配置由你负责
托管连接器	通常不需要	第三方服务	提供商管理的 API/MCP	设置简单，但凭据和活动数据会经过另一项服务
strava-mcp-bridge	否	本地 macOS 钥匙串	官方 Strava MCP	需要通过 Claude Code 一次性初始化；仅支持 Apple Silicon macOS

不同提供商的托管连接器行为各不相同。连接健身数据前，请先查看其数据流向和服务条款。

适合 / 不适合的情况

在以下条件全部满足时，适合使用此桥接程序：

• 你使用 Codex、OpenCode 或其他能够运行本地 stdio MCP 服务的客户端。
• 你拥有符合条件的 Strava 订阅，可使用 Strava 官方 MCP。
• 你不想创建和维护 Strava 开发者应用。
• 你倾向于在本地保管凭据，并采用谨慎的数据控制措施。
• 你使用的是 Apple Silicon Mac。

在以下任一条件成立时，请选择其他方式：

• Claude 的官方连接器已满足你的工作流需求。
• 你可以接受创建 Strava 开发者应用，并希望采用传统的 REST API 集成方式。
• 你的事实来源是 Garmin、Intervals.icu、Apple Health 或其他系统。
• 你需要 Linux、Windows 或 Intel Mac 支持。
• 你没有符合条件的 Strava 订阅。

要求

• Apple Silicon macOS（darwin arm64）
• Node.js 22+
• Xcode 命令行工具（xcode-select --install）
• 符合条件的 Strava 订阅
• 在 Claude Code 中成功完成一次官方 Strava MCP 授权

此桥接工具不要求付费 Claude 订阅。通过 Ollama 启动的 Claude Code 也已通过验证；关键组件是 Claude Code OAuth 客户端，而非模型后端。

安装

npm install -g strava-mcp-bridge

在用户级别显式安装随附的 Codex 技能：

strava-mcp-bridge skill install

此操作只会写入 $HOME/.agents/skills/strava-mcp-bridge，不会修改 Codex 或 MCP 配置。若要将技能保留在单个项目中：

strava-mcp-bridge skill install --project-dir /absolute/path/to/project

安装后启动新的 Codex 任务，然后调用 $strava-mcp-bridge。除非你检查目标路径并显式传入 --force，否则绝不会覆盖已有的不同技能内容。

1. 授权一次官方 Strava MCP

将官方端点添加到 Claude Code：

claude mcp add --transport http strava https://mcp.strava.com/mcp

在 Claude Code 中运行 /mcp，选择 strava，并完成 Strava 浏览器授权。这是唯一需要 Claude Code 的步骤。

2. 初始化本地桥接工具

strava-mcp-bridge bootstrap

bootstrap：

• 必要时构建原生 Keychain 辅助程序；
• 导入并接管已授权的刷新令牌链；
• 将桥接工具专用凭据存储在 macOS Keychain 中；
• 输出项目级 Codex MCP 配置片段；
• 绝不输出令牌值。

将生成的片段添加到目标项目的 .codex/config.toml，重启 Codex（或启动新任务），然后在启用活动工具前调用 health。

训练同步配置示例：

strava-mcp-bridge config codex \
  --profile training-sync \
  --stream-output-dir /absolute/path/to/your/project/strava-streams

生成的配置文件会开放以下工具：

• health
• eligibility
• list_activities
• get_activity_streams
• get_activity_performance

随附的 Codex 技能会引导 Agent 完成 doctor、bootstrap、项目级配置以及安全故障处理。检出源代码后，该技能会作为仓库技能提供；skill install 命令可让其他项目发现它。

工作原理

flowchart LR
    C["Codex / OpenCode"] -->|"stdio MCP"| B["strava-mcp-bridge"]
    B -->|"approved JSON-RPC + Bearer token"| S["Official Strava MCP"]
    B -->|"read / rotate credential"| K["macOS Keychain"]
    B -->|"full non-location streams"| F["Local 0600 files"]
    B -. "GPS / location blocked" .-> X["AI context"]

该桥接工具既是传输适配器，也是本地策略边界：

• 将远程 Streamable HTTP MCP 映射为本地 stdio MCP 服务；
• 除非工具名称明确列入允许列表，否则拒绝 tools/call；
• 将 tools/list 的结果过滤为本地允许列表中的工具；
• 默认仅向固定的官方 MCP 端点发送访问令牌；
• OAuth 刷新使用固定的 Strava 令牌端点和 MCP 资源；
• 过期后重新初始化 MCP 会话，并在 stdio 关闭时删除会话。

隐私默认设置

位置数据

get_activity_streams 要求显式指定流列表。允许的流如下：

time, heart_rate, velocity_smooth, cadence, altitude,
distance, temp, watts, grade_smooth, moving

转发前会拒绝位置／GPS／类似折线图的数据流。对于其他结构化工具响应，会递归地删除常见位置键、坐标文本、坐标数组、折线图、地图以及类似令牌的字段。对于不透明的非 JSON 文本和非文本内容块，则会默认拒绝。

大型数据流

完整的数据流数组绝不会返回到 MCP 客户端上下文中。它们会以原子方式写入当前用户拥有的目录（0700），并作为权限模式为 0600 的常规文件保存。工具结果仅包含路径、数据流名称、点数以及 omitted_from_context=true。

默认位置：

~/Library/Application Support/strava-mcp-bridge/streams/

除非提供 --yes，否则保留期限清理仅执行试运行：

strava-mcp-bridge streams prune --older-than-days 30
strava-mcp-bridge streams prune --older-than-days 30 --yes

完整的控制措施和剩余风险请参阅 SECURITY.md 和 THREAT_MODEL.md。

凭据生命周期

由桥接工具管理的 Keychain 项目是：

Strava MCP Bridge Native-credentials

显式导入是凭据所有权迁移，而非被动复制。 Strava 刷新令牌会轮换，因此，将令牌链交由桥接工具管理 可能会使 Claude Code 之前复制的刷新令牌失效。之后如果 Claude Code 需要重新连接，可以再次授权。

MCP 正常启动时只会读取由桥接工具管理的 Keychain 项目。它不会从 Claude Code 导入凭据，也不会修改 Claude Code 配置。

Keychain 权限对话框

在 bootstrap 期间，macOS 可能会显示两种不同的提示：

• /usr/bin/security 读取 Claude Code-credentials：选择 允许，而不是 始终允许。这只是显式的一次性导入。
• strava-keychain-helper 读取由桥接工具管理的项目：选择 允许 是 权限最小化的做法。始终允许 可避免重复提示，但需接受文档所述的同一用户辅助工具风险。

升级后，重新构建的辅助工具可能会触发新的提示。

常用命令

命令	用途
strava-mcp-bridge doctor	只读检查平台、辅助工具和凭据
strava-mcp-bridge bootstrap	设置辅助工具、凭据和配置片段
strava-mcp-bridge auth status --json	显示非敏感凭据元数据
strava-mcp-bridge skill install	在用户级别安装捆绑的 Codex 技能
strava-mcp-bridge skill install --project-dir <path>	在单个项目中安装
strava-mcp-bridge config codex --profile minimal	输出最简 Codex 配置
strava-mcp-bridge config codex --profile training-sync	输出骑行同步配置
strava-mcp-bridge streams prune --older-than-days 30	预览流数据保留清理
strava-mcp-bridge auth remove	预览移除桥接凭据
strava-mcp-bridge auth remove --yes	仅删除由桥接工具管理的凭据

请参阅 strava-mcp-bridge --help，了解端点、超时、数据目录和 诊断覆盖选项。

移除访问权限

strava-mcp-bridge auth remove          # dry run
strava-mcp-bridge auth remove --yes    # remove local bridge credential

这不会移除 Claude Code 的凭据。若要在 Strava 端撤销访问权限， 请在 Strava 的已连接应用设置中取消授权。

当前状态

• 实验性版本 0.1.x
• 仅支持 Apple Silicon 上的 macOS
• 使用官方 Strava MCP，而非重新实现 REST API
• 首次 OAuth 初始化仍需要 Claude Code
• 目前不存在经过验证、仅基于标准的动态客户端注册途径
• 已发布至官方 MCP Registry，名称为 io.github.millerchou/strava-mcp-bridge
• Strava 表示计划支持其他客户端

此限制出现在 OAuth 客户端注册／令牌签发阶段，而非大模型或简单的 User-Agent 检查。 在隔离测试期间，通用 RFC 7591 注册尝试遭到拒绝。

开发

npm test
npm run build:keychain-helper
npm pack --dry-run

测试使用本地模拟，不会连接 Strava，也不会读取 Keychain。

发布负责人说明见 RELEASING.md。

免责声明

这是一个非官方社区项目，与 Strava、Anthropic、OpenAI 或 OpenCode 维护者 均无关联，也未获其认可。Strava 可随时更改其 OAuth、MCP、订阅或客户端支持行为。