{
  "markdown": "# strava-mcp-bridge\n\n[![CI](https://github.com/millerchou/strava-mcp-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/millerchou/strava-mcp-bridge/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-1f2937.svg)](LICENSE)\n\n**Use Strava's official MCP from Codex, OpenCode, and other local stdio MCP\nclients without creating your own Strava developer app.**\n\nThe bridge runs locally on Apple Silicon macOS. Its OAuth credential is kept in\nmacOS Keychain, large activity streams stay in local files, and GPS/location\ndata is blocked before it can enter the AI context.\n\n![strava-mcp-bridge: official Strava MCP for Codex, with local credentials and local streams](https://raw.githubusercontent.com/millerchou/strava-mcp-bridge/main/docs/social-preview.png)\n\n## What It Enables\n\nOnce connected, a local coding agent can use Strava data as part of a real\nproject workflow instead of working from copied summaries or synthetic data.\n\n```text\nYou: Pull my new rides since the local watermark and rebuild my training dashboard.\n\nCodex:\n  3 new rides found through the official Strava MCP\n  full activity streams saved locally, omitted from model context\n  training summary and fitness chart rebuilt\n  no GPS, location, or polyline fields returned to the conversation\n```\n\nOther example tasks:\n\n- \"Compare heart-rate load across my rides this week.\"\n- \"Fetch the non-location streams for this activity and update my analysis.\"\n- \"Use my latest cycling data to refresh the PMC/TRIMP dashboard in this repo.\"\n\nThe bridge supplies the safe Strava connection. Your agent can then combine the\nresult with local scripts, notebooks, dashboards, or training-analysis code.\n\n## Why This Exists\n\nStrava publishes an [official MCP connector](https://support.strava.com/en-us/articles/15401531-strava-mcp-connector),\nbut its documented first-time authorization flow currently targets Claude\nclients. Codex supports MCP, yet it cannot currently complete this Strava OAuth\nbootstrap directly.\n\n`strava-mcp-bridge` fills that gap:\n\n1. You authorize the official Strava MCP once through Claude Code.\n2. You explicitly run `strava-mcp-bridge bootstrap`.\n3. The bridge migrates the authorized credential into its own Keychain item.\n4. It maintains the rotating refresh-token chain and forwards approved MCP\n   requests to `https://mcp.strava.com/mcp`.\n5. Normal Codex/OpenCode use no longer reads or invokes Claude Code.\n\nThis is not a Strava REST API wrapper and does not provide shared credentials or\nbypass user authorization.\n\n## Choose The Right Path\n\n| Path | Create your own Strava app? | Credential custody | Strava interface | Main tradeoff |\n|---|---:|---|---|---|\n| Official connector in Claude | No | Official client | Official Strava MCP | Simplest if Claude already fits your workflow |\n| Community self-hosted Strava MCP | Usually yes | Local | Strava REST API | Broad client support, but you own the app and OAuth plumbing |\n| Managed connector | Usually no | Third-party service | Provider-managed API/MCP | Easy setup, but credentials and activity data pass through another service |\n| **strava-mcp-bridge** | **No** | **Local macOS Keychain** | **Official Strava MCP** | One-time Claude Code bootstrap; Apple Silicon macOS only |\n\nManaged connector behavior varies by provider. Review its data path and terms\nbefore connecting fitness data.\n\n## Good Fit / Not A Fit\n\nUse this bridge when all of these are true:\n\n- You use Codex, OpenCode, or another client that can run local stdio MCP\n  servers.\n- You have access to Strava's official MCP through an eligible Strava\n  subscription.\n- You do not want to create and maintain a Strava developer app.\n- You prefer local credential custody and conservative data controls.\n- You are on an Apple Silicon Mac.\n\nUse another path when any of these are true:\n\n- Claude's official connector already covers your workflow.\n- Creating a Strava developer app is acceptable and you want a conventional\n  REST API integration.\n- Your source of truth is Garmin, Intervals.icu, Apple Health, or another system.\n- You need Linux, Windows, or Intel Mac support.\n- You do not have an eligible Strava subscription.\n\n## Requirements\n\n- Apple Silicon macOS (`darwin arm64`)\n- Node.js 22+\n- Xcode Command Line Tools (`xcode-select --install`)\n- An eligible Strava subscription\n- One successful official Strava MCP authorization in Claude Code\n\nA paid Claude subscription is not required by this bridge. The authorization\nhas also been validated with Claude Code launched through Ollama; the important\ncomponent is the Claude Code OAuth client, not the model backend.\n\n## Install\n\n```bash\nnpm install -g strava-mcp-bridge\n```\n\nInstall the bundled Codex skill explicitly at user scope:\n\n```bash\nstrava-mcp-bridge skill install\n```\n\nThis writes only to `$HOME/.agents/skills/strava-mcp-bridge`; it does not edit\nCodex or MCP configuration. To keep the skill inside one project instead:\n\n```bash\nstrava-mcp-bridge skill install --project-dir /absolute/path/to/project\n```\n\nStart a new Codex task after installation, then invoke\n`$strava-mcp-bridge`. Existing different skill content is never overwritten\nunless you review the target and pass `--force` explicitly.\n\n### 1. Authorize The Official Strava MCP Once\n\nAdd the official endpoint to Claude Code:\n\n```bash\nclaude mcp add --transport http strava https://mcp.strava.com/mcp\n```\n\nInside Claude Code, run `/mcp`, select `strava`, and complete the Strava browser\nauthorization. This is the only step that needs Claude Code.\n\n### 2. Bootstrap The Local Bridge\n\n```bash\nstrava-mcp-bridge bootstrap\n```\n\n`bootstrap`:\n\n- builds the native Keychain helper when needed;\n- imports and claims the authorized refresh-token chain;\n- stores the bridge-owned credential in macOS Keychain;\n- prints a project-scoped Codex MCP configuration snippet;\n- never prints token values.\n\nAdd the generated snippet to the target project's `.codex/config.toml`, restart\nCodex (or start a new task), then call `health` before enabling activity tools.\n\nFor a training sync configuration:\n\n```bash\nstrava-mcp-bridge config codex \\\n  --profile training-sync \\\n  --stream-output-dir /absolute/path/to/your/project/strava-streams\n```\n\nThe generated profile exposes:\n\n- `health`\n- `eligibility`\n- `list_activities`\n- `get_activity_streams`\n- `get_activity_performance`\n\nThe bundled [Codex skill](.agents/skills/strava-mcp-bridge/SKILL.md) guides the\nagent through `doctor`, `bootstrap`, project-level configuration, and safe\nfailure handling. A source checkout exposes it as a repository skill; the\n`skill install` command makes it discoverable from other projects.\n\n## How It Works\n\n```mermaid\nflowchart LR\n    C[\"Codex / OpenCode\"] -->|\"stdio MCP\"| B[\"strava-mcp-bridge\"]\n    B -->|\"approved JSON-RPC + Bearer token\"| S[\"Official Strava MCP\"]\n    B -->|\"read / rotate credential\"| K[\"macOS Keychain\"]\n    B -->|\"full non-location streams\"| F[\"Local 0600 files\"]\n    B -. \"GPS / location blocked\" .-> X[\"AI context\"]\n```\n\nThe bridge is both a transport adapter and a local policy boundary:\n\n- remote Streamable HTTP MCP is presented as a local stdio MCP server;\n- `tools/call` is denied unless its tool name is explicitly allowlisted;\n- `tools/list` is filtered to the local allowlist;\n- access tokens are sent only to the pinned official MCP endpoint by default;\n- OAuth refresh uses the pinned Strava token endpoint and MCP resource;\n- MCP sessions are reinitialized after expiry and deleted on stdio shutdown.\n\n## Privacy Defaults\n\n### Location Data\n\n`get_activity_streams` requires an explicit stream list. The accepted streams\nare:\n\n```text\ntime, heart_rate, velocity_smooth, cadence, altitude,\ndistance, temp, watts, grade_smooth, moving\n```\n\nLocation/GPS/polyline-like streams are rejected before forwarding. Other\nstructured tool responses are recursively redacted for common location keys,\ncoordinate text, coordinate arrays, polylines, maps, and token-like fields.\nOpaque non-JSON text and non-text content blocks fail closed.\n\n### Large Streams\n\nFull stream arrays are never returned to the MCP client context. They are\nwritten atomically to a current-user-owned directory (`0700`) as regular files\nwith mode `0600`. The tool result contains only the path, stream names, point\ncounts, and `omitted_from_context=true`.\n\nDefault location:\n\n```text\n~/Library/Application Support/strava-mcp-bridge/streams/\n```\n\nRetention cleanup is a dry run unless `--yes` is supplied:\n\n```bash\nstrava-mcp-bridge streams prune --older-than-days 30\nstrava-mcp-bridge streams prune --older-than-days 30 --yes\n```\n\nSee [SECURITY.md](SECURITY.md) and [THREAT_MODEL.md](THREAT_MODEL.md) for the\ncomplete controls and residual risks.\n\n## Credential Lifecycle\n\nThe bridge-owned Keychain item is:\n\n```text\nStrava MCP Bridge Native-credentials\n```\n\nThe explicit import is a credential ownership migration, not a passive copy.\nStrava refresh tokens rotate, so claiming the chain for bridge-owned operation\ncan make Claude Code's previous copied refresh token stale. Claude Code can\nreauthorize later if it needs its own connection again.\n\nNormal MCP startup reads only the bridge-owned Keychain item. It does not import\nfrom Claude Code or modify Claude Code configuration.\n\n### Keychain Permission Dialogs\n\nDuring `bootstrap`, macOS may show two different prompts:\n\n- `/usr/bin/security` reading `Claude Code-credentials`: choose **Allow**, not\n  **Always Allow**. This is the explicit one-time import.\n- `strava-keychain-helper` reading the bridge-owned item: **Allow** is the\n  least-privilege choice. **Always Allow** avoids repeat prompts but accepts the\n  documented same-user helper risk.\n\nA rebuilt helper may trigger a new prompt after an upgrade.\n\n## Useful Commands\n\n| Command | Purpose |\n|---|---|\n| `strava-mcp-bridge doctor` | Read-only platform/helper/credential check |\n| `strava-mcp-bridge bootstrap` | Set up helper, credential, and config snippet |\n| `strava-mcp-bridge auth status --json` | Show non-sensitive credential metadata |\n| `strava-mcp-bridge skill install` | Install the bundled Codex skill at user scope |\n| `strava-mcp-bridge skill install --project-dir <path>` | Install it in one project |\n| `strava-mcp-bridge config codex --profile minimal` | Print minimal Codex config |\n| `strava-mcp-bridge config codex --profile training-sync` | Print cycling-sync config |\n| `strava-mcp-bridge streams prune --older-than-days 30` | Preview stream retention cleanup |\n| `strava-mcp-bridge auth remove` | Preview bridge credential removal |\n| `strava-mcp-bridge auth remove --yes` | Delete only the bridge-owned credential |\n\nSee `strava-mcp-bridge --help` for endpoint, timeout, data-directory, and\ndiagnostic override options.\n\n## Removing Access\n\n```bash\nstrava-mcp-bridge auth remove          # dry run\nstrava-mcp-bridge auth remove --yes    # remove local bridge credential\n```\n\nThis never removes Claude Code's credential. To revoke access on Strava's side,\ndeauthorize the connection in Strava's connected-app settings.\n\n## Current Status\n\n- Experimental `0.1.x`\n- Apple Silicon macOS only\n- Official Strava MCP, not a REST API reimplementation\n- First OAuth bootstrap still requires Claude Code\n- No verified standards-only dynamic client registration path exists today\n- Published in the official MCP Registry as\n  `io.github.millerchou/strava-mcp-bridge`\n- Strava [says support for other clients is planned](https://support.strava.com/en-us/articles/15401526-strava-api-and-mcp-faq)\n\nThe restriction appears at OAuth client registration/token issuance, not at the\nLLM model or a simple User-Agent check. Generic RFC 7591 registration attempts\nwere rejected during isolated testing.\n\n## Development\n\n```bash\nnpm test\nnpm run build:keychain-helper\nnpm pack --dry-run\n```\n\nTests use local mocks. They do not contact Strava or read Keychain.\n\nRelease-owner instructions are in\n[RELEASING.md](https://github.com/millerchou/strava-mcp-bridge/blob/main/RELEASING.md).\n\n## Disclaimer\n\nThis is an unofficial community project. It is not affiliated with or endorsed\nby Strava, Anthropic, OpenAI, or the OpenCode maintainers. Strava can change its\nOAuth, MCP, subscription, or client-support behavior at any time.\n",
  "bytes": 12198,
  "sha": "f1b7d081494c819160757aa99f70235ec8b4342fb2dbc7c572d010bde7823e88",
  "repo_slug": "millerchou/strava-mcp-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_millerchou_strava_mcp_bridge_9ec3304f/readme"
}