Intervals MCP

Русская версия

一个自托管的只读 MCP 服务器，让 AI 助手可以访问运动员的 Intervals.icu 训练数据。

将运动手表、自行车码表、骑行台、Strava 或其他受支持的来源连接到 Intervals.icu。Intervals MCP 随后将标准化后的训练数据提供给 ChatGPT、Claude、Claude Code、Cursor、VS Code 及其他 MCP 客户端。其当前的集成列表请参阅 Intervals.icu；该列表会随时间变化。

服务器只发出 GET 请求。它无法在运动员的 Intervals.icu 账户中创建、编辑或删除任何内容。

助手可以读取的内容

• 运动员资料、时区、运动设置、区间、FTP、LTHR 和最大心率。

• 活动、详情、分段、间歇以及降采样后的数据流。

• 健康状况、体能、疲劳、HRV、睡眠、情绪和体重（如有）。

• 计划中的赛事、最佳成绩曲线、装备和训练库。

• 通过只读的原始工具访问 Intervals.icu v1 的其他 GET 端点。

较大的响应在到达模型之前会被压缩。空字段会被丢弃，数据流会经过降采样，摘要则使用完整的数据序列。

Related MCP server: intervals.mcp

快速开始

你需要一台带有公开主机名的 Ubuntu 或 Debian VPS。将该主机名的 DNS 记录指向服务器，并允许入站 TCP 端口 80 和 443。安装程序会在缺少 Docker、Compose、Git 和 uv 时自动安装它们：

curl -fsSL https://raw.githubusercontent.com/VictorForV/intervals-mcp/master/install.sh | sudo bash

如果你不想把远程脚本通过管道传给特权 shell，请在运行前先审阅 install.sh。在安装好前置条件后，克隆仓库并运行 ./manage.sh 仍然可以进行手动安装。

选择 Initial setup（初始设置）。管理器会询问公开主机名、一个简短的运动员名称，以及 Intervals.icu 的运动员 ID 和 API 密钥。ID 和密钥可在 Intervals.icu 的 Settings → Developer Settings 下获取。API 密钥使用隐藏输入。

管理器会创建仅限所有者访问的配置，生成一个强随机 URL 令牌，启动服务，并打印连接器 URL。之后运行 ./manage.sh 可以添加、列出、编辑或移除运动员，轮换 URL，重建、重启或检查服务。

连接 AI 客户端

每位运动员都会获得两个秘密 URL：

https://mcp.example.com/<secret>/mcp  # Streamable HTTP, preferred
https://mcp.example.com/<secret>/sse  # legacy SSE compatibility

请像对待密码一样对待完整的 URL。它授予对该运动员训练和健康数据的读取权限。

Claude 和 Claude Desktop

打开 Settings → Connectors → Add custom connector（设置 → 连接器 → 添加自定义连接器），输入 /mcp URL。可用性和组织权限取决于 Claude 套餐。请参阅当前的 Anthropic 说明。

Claude Code

管理器会打印一条可直接运行的命令：

claude mcp add --transport http intervals-alex https://mcp.example.com/<secret>/mcp

ChatGPT

将服务器添加为自定义应用/连接器，并使用你当前 ChatGPT 工作区接受的 URL。可用性、界面和管理员要求因套餐而异，且可能发生变化。请参阅当前的 OpenAI 文档。管理器会同时显示两种 URL 格式以供兼容。

其他客户端

远程 Streamable HTTP 客户端使用 /mcp，较旧的 SSE 客户端使用 /sse。请遵循客户端当前文档，切勿将秘密 URL 提交到共享配置中。

管理

交互式面板是推荐的界面：

./manage.sh

自动化场景下，同一界面提供子命令：

uv run intervals-mcp-admin add
uv run intervals-mcp-admin list
uv run intervals-mcp-admin show alex
uv run intervals-mcp-admin edit alex
uv run intervals-mcp-admin rotate alex
uv run intervals-mcp-admin remove alex

在交互式 shell 中应避免使用 --api-key，因为命令参数可能会保存在 shell 历史中或暴露在进程列表中。省略该参数即可使用隐藏输入。

本地 stdio 模式

对于单个运动员和使用本地进程的客户端，将 .env.example 复制为 .env，配置 Intervals.icu 凭据，然后运行：

uv run intervals-mcp

安全模型

• Intervals.icu 请求是只读的（GET）。

• 每位运动员都有独立的 API 客户端和独立的随机路径令牌。

• .env 和 users.toml 已被 gitignore，并以模式 0600 写入。

• API 密钥和路径令牌不会出现在应用和代理的访问日志中。

• 公共服务通过 Caddy 使用 HTTPS。

• users.toml 以只读方式挂载到容器中。

路径令牌即是持有者认证：任何持有该 URL 的人都可以读取该运动员的数据。如果令牌泄露，可通过 ./manage.sh 轮换。报告问题请参阅 SECURITY.md。

开发

uv sync
uv run pytest

测试使用完全合成的、符合 API 结构的夹具数据，不发起任何网络请求。使用 uv run python scripts/generate_fixtures.py 重新生成它们。

开发指南请参阅 CONTRIBUTING.md。

许可证

MIT — 参见 LICENSE。