strava-mcp-bridge

Use Strava's official MCP from Codex, OpenCode, and other local stdio MCP clients without creating your own Strava developer app.

The bridge runs locally on Apple Silicon macOS. Its OAuth credential is kept in macOS Keychain, large activity streams stay in local files, and GPS/location data is blocked before it can enter the AI context.

What It Enables

Once connected, a local coding agent can use Strava data as part of a real project workflow instead of working from copied summaries or synthetic data.

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

Other example tasks:

• "Compare heart-rate load across my rides this week."
• "Fetch the non-location streams for this activity and update my analysis."
• "Use my latest cycling data to refresh the PMC/TRIMP dashboard in this repo."

The bridge supplies the safe Strava connection. Your agent can then combine the result with local scripts, notebooks, dashboards, or training-analysis code.

Why This Exists

Strava publishes an official MCP connector, but its documented first-time authorization flow currently targets Claude clients. Codex supports MCP, yet it cannot currently complete this Strava OAuth bootstrap directly.

strava-mcp-bridge fills that gap:

1. You authorize the official Strava MCP once through Claude Code.
2. You explicitly run strava-mcp-bridge bootstrap.
3. The bridge migrates the authorized credential into its own Keychain item.
4. It maintains the rotating refresh-token chain and forwards approved MCP requests to https://mcp.strava.com/mcp.
5. Normal Codex/OpenCode use no longer reads or invokes Claude Code.

This is not a Strava REST API wrapper and does not provide shared credentials or bypass user authorization.

Choose The Right Path

Managed connector behavior varies by provider. Review its data path and terms before connecting fitness data.

Good Fit / Not A Fit

Use this bridge when all of these are true:

• You use Codex, OpenCode, or another client that can run local stdio MCP servers.
• You have access to Strava's official MCP through an eligible Strava subscription.
• You do not want to create and maintain a Strava developer app.
• You prefer local credential custody and conservative data controls.
• You are on an Apple Silicon Mac.

Use another path when any of these are true:

• Claude's official connector already covers your workflow.
• Creating a Strava developer app is acceptable and you want a conventional REST API integration.
• Your source of truth is Garmin, Intervals.icu, Apple Health, or another system.
• You need Linux, Windows, or Intel Mac support.
• You do not have an eligible Strava subscription.

Requirements

• Apple Silicon macOS (darwin arm64)
• Node.js 22+
• Xcode Command Line Tools (xcode-select --install)
• An eligible Strava subscription
• One successful official Strava MCP authorization in Claude Code

A paid Claude subscription is not required by this bridge. The authorization has also been validated with Claude Code launched through Ollama; the important component is the Claude Code OAuth client, not the model backend.

Install

npm install -g strava-mcp-bridge

Install the bundled Codex skill explicitly at user scope:

strava-mcp-bridge skill install

This writes only to $HOME/.agents/skills/strava-mcp-bridge; it does not edit Codex or MCP configuration. To keep the skill inside one project instead:

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

Start a new Codex task after installation, then invoke $strava-mcp-bridge. Existing different skill content is never overwritten unless you review the target and pass --force explicitly.

1. Authorize The Official Strava MCP Once

Add the official endpoint to Claude Code:

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

Inside Claude Code, run /mcp, select strava, and complete the Strava browser authorization. This is the only step that needs Claude Code.

2. Bootstrap The Local Bridge

strava-mcp-bridge bootstrap

bootstrap:

• builds the native Keychain helper when needed;
• imports and claims the authorized refresh-token chain;
• stores the bridge-owned credential in macOS Keychain;
• prints a project-scoped Codex MCP configuration snippet;
• never prints token values.

Add the generated snippet to the target project's .codex/config.toml, restart Codex (or start a new task), then call health before enabling activity tools.

For a training sync configuration:

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

The generated profile exposes:

• health
• eligibility
• list_activities
• get_activity_streams
• get_activity_performance

The bundled Codex skill guides the agent through doctor, bootstrap, project-level configuration, and safe failure handling. A source checkout exposes it as a repository skill; the skill install command makes it discoverable from other projects.

How It Works

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"]

The bridge is both a transport adapter and a local policy boundary:

• remote Streamable HTTP MCP is presented as a local stdio MCP server;
• tools/call is denied unless its tool name is explicitly allowlisted;
• tools/list is filtered to the local allowlist;
• access tokens are sent only to the pinned official MCP endpoint by default;
• OAuth refresh uses the pinned Strava token endpoint and MCP resource;
• MCP sessions are reinitialized after expiry and deleted on stdio shutdown.

Privacy Defaults

Location Data

get_activity_streams requires an explicit stream list. The accepted streams are:

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

Location/GPS/polyline-like streams are rejected before forwarding. Other structured tool responses are recursively redacted for common location keys, coordinate text, coordinate arrays, polylines, maps, and token-like fields. Opaque non-JSON text and non-text content blocks fail closed.

Large Streams

Full stream arrays are never returned to the MCP client context. They are written atomically to a current-user-owned directory (0700) as regular files with mode 0600. The tool result contains only the path, stream names, point counts, and omitted_from_context=true.

Default location:

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

Retention cleanup is a dry run unless --yes is supplied:

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

See SECURITY.md and THREAT_MODEL.md for the complete controls and residual risks.

Credential Lifecycle

The bridge-owned Keychain item is:

Strava MCP Bridge Native-credentials

The explicit import is a credential ownership migration, not a passive copy. Strava refresh tokens rotate, so claiming the chain for bridge-owned operation can make Claude Code's previous copied refresh token stale. Claude Code can reauthorize later if it needs its own connection again.

Normal MCP startup reads only the bridge-owned Keychain item. It does not import from Claude Code or modify Claude Code configuration.

Keychain Permission Dialogs

During bootstrap, macOS may show two different prompts:

• /usr/bin/security reading Claude Code-credentials: choose Allow, not Always Allow. This is the explicit one-time import.
• strava-keychain-helper reading the bridge-owned item: Allow is the least-privilege choice. Always Allow avoids repeat prompts but accepts the documented same-user helper risk.

A rebuilt helper may trigger a new prompt after an upgrade.

Useful Commands