Strava Activity MCP Server

Strava活动MCP服务器

  ](https://pypistats.org/packages/strava-activity-mcp-server) ](https://pepy.tech/projects/strava-activity-mcp-server)

一个小型的模型上下文协议（MCP）服务器，将Strava运动员数据暴露给语言模型工具。

在第一次基于浏览器的授权后，服务器使用保存的 refresh_token 自动刷新您的会话；在后续运行中不需要进一步的URL重定向登录。

该包提供了一个轻量级的MCP服务器，该服务器与Strava API通信，并公开了语言模型或其他本地工具可以调用的一些辅助工具（授权URL、令牌交换/刷新和获取运动员活动）。

该项目旨在本地使用（例如与Claude MCP集成），并在PyPI上发布为 strava-activity-mcp-server.

安装

使用pip从PyPI安装（建议在虚拟环境中安装）：

pip install strava-activity-mcp-server

需求

• Python>=3.10（请参见 pyproject.toml)
• 套餐取决于 mcp[cli] 和 requests （从PyPI安装）。

快速开始

安装后，您可以使用提供的控制台脚本或通过导入和调用来运行MCP服务器 main().

通过控制台脚本运行（在中定义的入口点 pyproject.toml):

strava-activity-mcp-server

或者，从Python：

from strava_activity_mcp_server import main
main()

默认情况下，服务器启动MCP运行时；当与MCP感知客户端（例如Msty MCP或其他一些MCP集成，如Claude、LM Tool等）一起使用时，暴露的工具变得可调用。

身份验证（Strava OAuth）

此服务器需要Strava OAuth凭据才能访问运动员数据。您将需要：

• STRAVA_CLIENT_ID
• STRAVA_CLIENT_SECRET

步骤：

1. 在创建Strava API应用程序https://www.strava.com/settings/api并记下您的客户端ID和客户端密码。使用 localhost 作为授权回调域。

1. 初始授权：调用 strava.auth.url 工具生成授权URL（请参阅下面的图像），在浏览器中打开它，并授予访问权限。仅在第一次获得授权码时才需要此步骤。

1. 复制 code 从重定向的URL（下图）。使用提供的工具将其兑换为访问/刷新令牌。

1. 在初始授权之后，一个名为 strava_mcp_tokens.json 创建并存储在您的主目录中（例如在Windows上： C:\\Users\\\\strava_mcp_tokens.json).此文件包含您的 refresh_token，将自动用于后续登录。首次授权后，您不需要再次打开浏览器流；未来的运行将刷新本地存储的访问令牌 refresh_token.

Windows上推荐的凭据设置（简单且持久）

为了避免将真实凭据放入MCP客户端JSON文件中，请将凭据设置为Windows用户环境变量一次：

1. 打开“开始”并搜索： Edit environment variables for your account
2. 在...之下 用户变量，创建：

• STRAVA_CLIENT_ID =您的数字客户ID（仅限数字，无引号）
• STRAVA_CLIENT_SECRET =您的客户机密

1. 完全重新启动MCP客户端（例如Msty），以便它获取新变量。

PowerShell替代方案（一次性设置）：

[Environment]::SetEnvironmentVariable("STRAVA_CLIENT_ID", "YOUR_ID_HERE", "User")
[Environment]::SetEnvironmentVariable("STRAVA_CLIENT_SECRET", "YOUR_SECRET_HERE", "User")

笔记：

• 不要在保存的值中包含周围的引号（例如store 12345，不 "12345").
• STRAVA_CLIENT_ID 必须是整数值；否则工具返回： STRAVA_CLIENT_ID must be an integer.

暴露的工具（服务器提供的工具）

MCP服务器公开了以下工具（显示了工具ID）。这些映射到中的函数 src/strava_activity_mcp_server/strava_activity_mcp_server.py 并涵盖初始授权和后续刷新流程。

规范工具ID使用点符号（例如 strava.auth.url).URI样式别名（例如 strava://auth/url)为了向后兼容性而保留。

• strava.auth.url （别名： strava://auth/url)--构建Strava OAuth授权URL。

- 输入： client_id （int，可选；读取 STRAVA_CLIENT_ID 如果省略） - 输出：授权URL字符串

• strava.auth.refresh （别名： strava://auth/refresh)--使用刷新令牌刷新令牌并在本地持久化它们。

- 输入： refresh_token （str）， client_id （int，可选）， client_secret （str，可选） - 输出：仅净化状态（不返回令牌值）

• strava.athlete.stats （别名： strava://athlete/stats)--交换授权 code 获取令牌，然后获取最近活动的一页。

- 输入： code （str）， client_id （int，可选）， client_secret （str，可选）， after （int，可选）， before （int，可选）， page （int，可选）， per_page （int，可选） - 输出： { activities, token_status, save } （标记值已编辑）

• strava.athlete.stats-with-token （别名： strava://athlete/stats-with-token)--使用现有访问令牌获取最近活动的一页。

- 输入： access_token （str）， after （int，可选）， before （int，可选）， page （int，可选）， per_page （int，可选） - 输出：活动列表（JSON）

• strava.auth.save （别名： strava://auth/save)--将令牌保存到 ~\strava_mcp_tokens.json.

- 输入： tokens 字典 - 输出： { ok, path } 或错误

• strava.auth.load （别名： strava://auth/load)--从加载令牌 ~\strava_mcp_tokens.json.

- 输入：无 - 输出： { ok, path, token_status } 或错误（标记值已编辑）

• strava.athlete.refresh-and-stats （别名： strava://athlete/refresh-and-stats)--加载保存的刷新令牌，刷新访问令牌，保存它，并获取一页活动。

- 输入： client_id （int，可选）， client_secret （str，可选）， after （int，可选）， before （int，可选）， page （int，可选）， per_page （int，可选） - 输出： { activities, token_status } （标记值已编辑）

• strava.session.start （别名： strava://session/start)——方便输入：如果令牌存在，刷新并获取；否则返回一个auth URL以开始初始授权。

- 输入： client_id （int，可选）， client_secret （str，可选）， after （int，可选）， before （int，可选）， page （int，可选）， per_page （int，可选） - 输出：刷新活动有效负载 token_status 元数据，或 { auth_url, token_file_checked }

• strava.athlete.fetch-all （别名： strava://athlete/fetch-all)--确定地获取所有页面。

- 输入： access_token （可选）， after （可选）， before （可选）， per_page （默认值 50), max_pages （默认值 10), retry_count （默认值 2), detail_level (summary 违约，或 detailed), detail_max_rows （上限） - 停止行为：迭代直到页面大小为 < per_page 或 max_pages 已达到。 - 输出（默认）：压缩摘要+元数据；仅在明确请求时才显示详细行。

这些工具旨在供MCP客户端调用。

• strava.trimp.banister --获取所有运动员活动（分页），筛选出心率活动，计算Banister TRIMP，并对可变性进行排名。

- 别名： strava://trimp/account-report - 输入： sex （男性/女性）， hr_rest, hr_max，可选分页(per_page, max_pages)和过滤器(after, before)，加 detail_level (summary 违约，或 detailed)以及 detail_max_rows （上限） - 输出（默认）：紧凑的TRIMP摘要和运动可变性；详细的 activities 行仅包含在显式详细模式中。

活动筛选

服务器现在支持通过URL参数对Strava活动进行高级过滤。以下筛选器参数可用于活动相关工具：

• after （int，可选）：一个历元时间戳，用于过滤在特定时间后发生的活动
• before （int，可选）：一个历元时间戳，用于过滤在特定时间之前发生的活动
• page （int，可选）：要检索的活动的页码（默认值=1）
• per_page （int，可选）：每页活动数（最大=200）

- 默认值： strava.athlete.stats 使用30；为了更安全地使用LLM上下文，分析流默认为50。

过滤示例

• 获取过去30天的活动： after=1640995200 （2022年1月1日的纪元时间戳）
• 从特定日期范围获取活动： after=1640995200&before=1643673600
• 获取前10项活动： page=1&per_page=10
• 从第2页获取活动，每页50个： page=2&per_page=50

这些过滤器使用以下工具：

• strava.athlete.stats / strava://athlete/stats
• strava.athlete.stats-with-token / strava://athlete/stats-with-token
• strava.athlete.refresh-and-stats / strava://athlete/refresh-and-stats
• strava.session.start / strava://session/start
• strava.athlete.fetch-all / strava://athlete/fetch-all

示例流程

1. 获取授权URL并检索令牌

• 呼叫 strava.auth.url （或 strava://auth/url)与你的 client_id 并在浏览器中打开返回的URL。
• 授权后，Strava将提供 code.

1. 获取最近的活动

• 使用 strava.athlete.stats 用于单页活动检索。如果访问令牌已过期，请使用刷新流获取新的访问令牌。

1. 获取已筛选的活动

• 获取过去7天的活动：使用 strava.athlete.stats-with-token 和 after 参数设置为纪元时间戳
• 获取分页结果：使用 page 和 per_page 控制返回活动数量的参数
• 从特定日期范围获取活动：合并 after 和 before 参数

1. 可靠地获取所有页面

• 使用 strava.athlete.fetch-all 用于完整的历史检索。
• 对于所有活动（包括Banister TRIMP）的分析/报告，首选此高级工具或 strava.trimp.banister 它现在在内部使用确定性分页。

客户端配置示例和快速检查器测试

任何支持MCP的客户端都可以使用类似于以下的配置启动服务器（示例文件通常称为 mcp.json 或 config.json).

建议Msty在Windows上使用：将真实凭据从JSON文件中删除，并依赖于Windows用户环境变量。

{
  "command": "uvx",
  "args": [
    "strava-activity-mcp-server"
  ]
}

如果您的MCP客户端支持环境变量插值，则此模式也可能适用：

{
  "command": "uvx",
  "args": [
    "strava-activity-mcp-server"
  ],
  "env": {
    "STRAVA_CLIENT_ID": "${STRAVA_CLIENT_ID}",
    "STRAVA_CLIENT_SECRET": "${STRAVA_CLIENT_SECRET}"
  }
}

如果您的MCP客户端不支持插值，它可能会传递文字文本 ${STRAVA_CLIENT_ID} 和 ${STRAVA_CLIENT_SECRET}。在这种情况下，请删除 env 阻止并依赖继承的Windows用户变量。

要使用模型上下文协议检查器工具快速测试服务器，请运行：

npx @modelcontextprotocol/inspector uvx strava-activity-mcp-server

这将尝试使用启动服务器 uvx 将检查器传输并连接到名为的正在运行的MCP服务器实例 strava-activity-mcp-server.

Msty Studio中使用MCP的聊天示例

贡献

欢迎捐款。请打开问题或拉取请求，其中包括明确的描述和测试（如适用）。

许可证

此项目根据GNU通用公共许可证获得许可——请参阅 LICENSE 文件以获取详细信息。

链接

• 来源：存储库根目录
• 文件说明：见 README.md 例如MCP配置
• 更改日志：请参阅 CHANGELOG.md 上次更改