strava-openapi-mcp

本地 Python MCP 服务器，作为 MCP 客户端（尤其是 OpenCode）与 Strava REST API 之间的通用代理。工具并非按端点逐一实现：它们在启动时根据 Strava 官方 Swagger 2.0 规范自动生成。

仓库中包含该规范及其引用的 schema 文档的副本。因此，启动时无需互联网访问即可构建工具列表。update-spec 命令在验证后刷新用户副本。

架构

openapi.py 加载并验证 Swagger，解析本地引用，并规范化操作。tools.py 将每个操作转换为带有生成 JSON Schema 的 MCP 工具。client.py 构建 URL、参数、JSON 请求体和 multipart 表单，而无需单独了解 Strava 端点。auth.py 处理本地 OAuth 流程和令牌刷新。server.py 通过 MCP stdio 暴露所有内容，而 cli.py 提供维护命令。

Strava 当前发布的规范是 Swagger 2.0，info.version 为 3.0.0。该捆绑包有意视为可替换数据：如果规范中出现新端点，则会自动发现。

Related MCP server: MCP OpenAPI Connector

前提条件和本地安装

推荐使用 Python 3.12+ 和 uv。

git clone https://github.com/Arbodgad/strava-openapi-mcp.git
cd strava-openapi-mcp
uv sync
uv run strava-mcp list-tools

使用以下命令启动 MCP 服务器：

uv run strava-mcp

服务器在 MCP stdin/stdout 传输上保持活动状态。应用程序日志发送到 stderr。在 stdio 传输期间，不得将任何诊断日志写入 stdout。

创建 Strava 应用程序

1. 打开 https://www.strava.com/settings/api。

2. 创建一个应用程序，并记下其 Client ID 和 Client Secret。

3. Strava 接受 localhost 和 127.0.0.1 作为回调域名。默认回调为 http://127.0.0.1:8765/callback。

可以通过环境变量提供凭据：

export STRAVA_CLIENT_ID="..."
export STRAVA_CLIENT_SECRET="..."

或者在 ~/.config/strava-mcp/credentials.json 中提供，权限为 0600：

{
  "client_id": "...",
  "client_secret": "..."
}

环境变量优先。密钥永远不会显示或写入日志。

OAuth

运行一次：

strava-mcp auth

浏览器打开 Strava 授权页面。本地回调将授权码交换为 access_token、refresh_token、expires_at 以及授予的 scope。令牌存储在 ~/.config/strava-mcp/tokens.json 中，权限为 0600。服务器会自动刷新过期的访问令牌，并在 Strava 返回轮换的刷新令牌时持久化它。

默认情况下，会请求规范声明的所有 scope。要请求子集：

export STRAVA_OAUTH_SCOPES="activity:read,activity:write"

官方描述会被分析以推断显式 scope。接受 activity:read 或 activity:read_all 的读取端点表示为替代项。条件 scope（例如私有活动的 activity:read_all）会显示给 LLM，并且原始的 Strava 错误仍然可见。

配置

支持的变量：

别名 STRAVA_MCP_ALLOW_WRITE 和 STRAVA_MCP_ALLOW_DELETE 也被接受。strava-mcp show-config 仅显示非机密配置视图。

推荐值为 STRAVA_ALLOW_WRITE=true 和 STRAVA_ALLOW_DELETE=false。POST、PUT 和 PATCH 方法默认不被阻止。当规范包含 DELETE 方法时，会生成这些方法，但在 STRAVA_ALLOW_DELETE=false 时，它们会从 MCP 工具列表中过滤掉。

首次启动

export STRAVA_CLIENT_ID="..."
export STRAVA_CLIENT_SECRET="..."
strava-mcp auth
strava-mcp list-tools
strava-mcp

用户规范副本优先。如果不存在，则使用捆绑的官方规范，启动时不会下载任何内容。

更新规范

strava-mcp update-spec

该命令下载 STRAVA_OPENAPI_URL，验证 Swagger 文档，然后下载引用的 JSON 文档。只有在整个下载和验证过程成功完成后，才会替换现有副本。会显示报告的版本和引用的 schema 数量。

要强制使用不同的路径：

STRAVA_OPENAPI_PATH="$HOME/.config/strava-mcp/openapi.json" strava-mcp update-spec

通过 Git 使用 uvx 直接安装

pyproject.toml 声明了可执行文件和所有依赖项。无需手动安装 Python 或克隆：

uvx --from git+https://github.com/Arbodgad/strava-openapi-mcp strava-mcp auth
uvx --from git+https://github.com/Arbodgad/strava-openapi-mcp strava-mcp

要立即使用新提交，尽管有 uv 缓存：

uvx --refresh --from git+https://github.com/Arbodgad/strava-openapi-mcp strava-mcp

OpenCode 配置

将服务器添加到 OpenCode 配置中：

{
  "mcp": {
    "strava": {
      "type": "local",
      "command": [
        "uvx",
        "--from",
        "git+https://github.com/Arbodgad/strava-openapi-mcp",
        "strava-mcp"
      ],
      "enabled": true
    }
  }
}

在启动 OpenCode 的环境中导出变量，或使用 credentials.json，而不是将机密提交到此文件。在启动 OpenCode 之前，为同一本地账户运行一次 strava-mcp auth。

生成的工具和示例

名称源自 operationId，规范化为 snake case，仅在必要时添加 HTTP 方法前缀以避免歧义。例如，使用当前规范：

UpdatableActivity 的请求体参数被扁平化到 PUT 工具中。因此，代理可以做出概念上等效的调用：

put_update_activity_by_id(id=123456789, name="Long Z2 run")
put_update_activity_by_id(id=123456789, description="Easy aerobic endurance session, good sensations.")

其他自然语言请求示例：

• “列出我最近的跑步活动”：使用 get_logged_in_athlete_activities，然后过滤返回的结果。

• “读取活动 123 的详细信息”：使用 get_activity_by_id(id=123)。

• “获取 123 的距离和心率流”：使用 get_activity_streams(id=123, keys=["distance", "heartrate"], key_by_type=true)。

• “获取我的统计数据”：获取已认证的运动员，然后使用 get_stats(id=...)。

分页完全由规范中的参数控制（page、per_page、before、after、page_size、after_cursor 等）。服务器永远不会自动启动长序列的页面请求。

写入和危险操作

MCP 描述中包含 This operation modifies Strava data（用于 POST/PUT/PATCH）和 WARNING（用于 DELETE）。如果 STRAVA_ALLOW_WRITE=false，写入工具会返回显式错误。如果 STRAVA_ALLOW_DELETE=false，DELETE 工具不会出现在 list_tools 中，直接调用会被拒绝。

HTTP 错误会保留状态、端点、Strava 消息和可用的速率限制头，例如：

HTTP 401 Unauthorized
Endpoint: PUT /activities/{id}
Message: Invalid or expired token

204 响应变为最小对象 { "status": "success", "http_status": 204 }。JSON 响应保留 Strava 字段名称。

CLI 命令

strava-mcp                       # MCP stdio server
strava-mcp auth                  # Browser OAuth + localhost callback
strava-mcp update-spec           # Validated update of the local copy
strava-mcp show-config           # Non-secret configuration
strava-mcp list-tools            # Method, endpoint, tool, and summary
strava-mcp list-tools --schemas  # Also display each inputSchema JSON

list-tools --schemas 对于诊断拒绝 schema 的 MCP 客户端很有用。JSON Schema 关键字（如 required）会显示在相关的 schema 级别；名为 required 的 Strava 属性仍保留在 properties 下。

测试和开发

uv run pytest
uv run ruff check .

测试使用模拟的 HTTP 传输，不会联系 Strava。针对 Strava 的集成测试有意不自动运行。

故障排除

• No Strava authorization found：使用正确的凭据运行 strava-mcp auth。

• OAuth scope missing：使用 STRAVA_OAUTH_SCOPES 中请求的 scope 再次运行 strava-mcp auth。

• Spec update aborted：之前的本地副本保持不变；检查网络或移除自定义的 STRAVA_OPENAPI_PATH。

• 没有 DELETE 工具：这是默认行为；设置 STRAVA_ALLOW_DELETE=true 并重启。

• 与 stdout 相关的 MCP 错误：不要在服务器代码中添加 print 调用；日志必须使用配置为 stderr 的 logging。

• OAuth 端口已被占用：将 STRAVA_CALLBACK_PORT 设置为可用端口，如有必要，在 Strava 应用程序中注册 localhost 域名。

安全

客户端密钥、访问令牌和刷新令牌永远不会包含在日志、MCP 描述或错误消息中。本地凭据和令牌文件被 Git 忽略，并以 0600 权限写入。切勿提交 .env、credentials.json 或 tokens.json。