内容
# intervals-mcp
个人只读MCP服务器和查询单个Intervals.icu运动员的CLI。
它的用途是回答以下问题：
- "我今天做了什么？"
- "显示我最近的训练记录，包括训练负荷和脱耦信息。"
- "这周我的日程安排是什么？"
- "获取该活动记录并包含训练区间。"
- "今天我的恢复/健康状况如何？"
服务器可以在本地运行，无需身份验证，也可以远程运行在Supabase OAuth/OIDC后面。
CLI使用与MCP服务器相同的只读Intervals.icu客户端。
您需要Go 1.26.3或`go.mod`中声明的版本，以及Intervals.icu API密钥和运动员ID。
使用以下命令安装统一的CLI：
```sh
go install github.com/teoruiz/intervals-mcp/cmd/intervals@latest
```
在标记版本发布之前，`@latest`解析为默认分支上的最新提交。要从检出构建：
```sh
git clone https://github.com/teoruiz/intervals-mcp
go install ./cmd/intervals
```
兼容性二进制文件仍然可用：
```sh
go install github.com/teoruiz/intervals-mcp/cmd/intervals-cli@latest
go install github.com/teoruiz/intervals-mcp/cmd/intervals-mcp@latest
```
## 功能列表
MCP服务器公开了以下工具：
| 工具 | 数据公开 |
| --- | --- |
| `today_context` | 今日活动、健康/恢复数据、运动员摘要、计划事件和燃料供应情况。 |
| `list_recent_activities` | 按日期降序排列的最近Intervals.icu活动记录。 |
| `get_activity` | 按ID获取单个活动记录，可选包含区间数据。 |
| `get_recovery` | 获取某日期的健康和健身摘要数据。 |
| `list_wellness` | 获取某日期范围内的每日健康记录，包括自定义健康字段。 |
| `list_calendar` | 获取计划的工作安排、笔记和其他日历事件。 |
| `search` | 搜索最近的活动记录、今日恢复数据和即将到来的计划事件。 |
| `fetch` | 获取`search`返回的记录，如活动记录、恢复日期或日历事件。 |
在底层，目前只读取了Intervals.icu的以下区域：
- 运动员基本信息：ID、姓名、邮箱和时区；
- 运动员摘要：健身、疲劳、状态、坡道速率、训练负荷、卡路里、距离、移动时间、体重、eFTP、时间分区和类别摘要；
- 活动记录和活动详情：名称、类型、日期、距离、移动/累计时间、卡路里、碳水化合物、训练负荷、ATL/CTL、心率、强度、效率、功率/心率、脱耦、RPE/感觉、描述、标签、区间摘要和可选区间记录；
- 健康/恢复记录：CTL/ATL、坡道速率、体重、静息心率、心率变异性、卡路里消耗、睡眠、酸痛、疲劳、压力、情绪、动力、补水、准备度、步数、SpO2、呼吸率、VO2最大值、血压、评论、宏量营养素和自定义健康字段（例如Garmin压力或身体电池，当这些键在Intervals.icu Garmin设置中启用时）；
- 日历事件：计划工作安排、笔记、日期、持续时间/距离/负荷目标、强度、碳水化合物、室内标志和标签。
它不会在Intervals.icu中创建、更新或删除任何内容。Intervals客户端只执行经过身份验证的`GET`请求。
捆绑的`docs/openapi-spec.json`只是上游Intervals.icu参考快照。它包含上游写/删除端点，但这些端点并未被此项目公开。参见`docs/README.md`。
## 快速开始：本地MCP
_stdio_模式是日常MCP使用中最容易的方式，在您的本地机器上按需启动，不需要单独的HTTP服务器。
1. 安装CLI：
```sh
go install github.com/teoruiz/intervals-mcp/cmd/intervals@latest
```
2. 创建您的配置文件：
```sh
intervals config init
```
这会将dotenv配置文件写入`$XDG_CONFIG_HOME/intervals-mcp/config.env`或`~/.config/intervals-mcp/config.env`（当`XDG_CONFIG_HOME`未设置时）。
3. 使用以下命令和参数注册_stdio_ MCP：
```text
命令：intervals
参数：["mcp", "stdio"]
```
示例MCP客户端JSON：
```json
{
"mcpServers": {
"intervals": {
"command": "intervals",
"args": ["mcp", "stdio"]
}
}
}
```
然后询问您的MCP客户端类似的问题：
```text
使用intervals总结今天的训练情况。
使用intervals列出我最近10次活动记录。
使用intervals搜索阈值骑行。
使用intervals显示本周我的计划工作安排。
使用intervals绘制过去一个月我的压力、心率变异性和睡眠情况。
获取该搜索结果中的第一个活动记录并包含区间。
```
直接调用MCP工具的示例输入：
```jsonl
{"tool": "today_context", "arguments": {"date": "2026-06-02"}}
{"tool": "list_recent_activities", "arguments": {"oldest": "2026-05-01", "newest": "2026-06-02", "limit": 10}}
{"tool": "get_activity", "arguments": {"id": "ACTIVITY_ID", "include_intervals": true}}
{"tool": "get_recovery", "arguments": {"date": "2026-06-02"}}
{"tool": "list_wellness", "arguments": {"oldest": "2026-05-05", "newest": "2026-06-02"}}
{"tool": "list_calendar", "arguments": {"oldest": "2026-06-02", "newest": "2026-06-09", "categories": ["WORKOUT"]}}
{"tool": "search", "arguments": {"query": "threshold"}}
{"tool": "fetch", "arguments": {"id": "activity:ACTIVITY_ID"}}
```
如果您的MCP客户端需要HTTP而不是_stdio_，请继续使用兼容性服务器：
```sh
intervals-mcp --local
# 或从仓库：
go run -buildvcs=false ./cmd/intervals-mcp --local
```
在`http://127.0.0.1:8080/mcp`注册HTTP客户端。
HTTP本地模式是无身份验证的。请将其绑定到`127.0.0.1`；任何可以访问该地址的内容都可以读取配置的运动员数据。
## CLI示例
CLI只需要Intervals.icu环境变量。
```sh
intervals today
intervals activities --oldest 2026-05-01 --newest 2026-06-02 --limit 10
intervals activity <id> --intervals --json
intervals recovery --date 2026-06-02
intervals wellness --oldest 2026-05-05 --newest 2026-06-02
intervals calendar --category WORKOUT
intervals search ride
intervals explore
```
有用的配置命令：
```sh
intervals config init
intervals config path
intervals config doctor
intervals config show
```
使用`--env PATH`加载特定的dotenv文件，并使用`--json`输出可管道传输的数据。`intervals-cli`仍然可用于现有的脚本，但新安装应使用`intervals`。
## 带有Supabase的远程MCP
对于远程MCP服务器，请在`.env`中填写经过身份验证的服务器字段：
```sh
MCP_PUBLIC_URL=https://your-domain.example
SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_ANON_KEY=...
OIDC_ALLOWED_EMAIL=you@example.com
```
Supabase设置：
- 启用邮箱/密码登录；
- 启用Supabase OAuth服务器；
- 启用动态客户端注册；
- 将授权路径设置为`/oauth/consent`；
- 可选地，如果这些提供者在Supabase中启用并希望添加额外的登录按钮，请设置`SUPABASE_OAUTH_PROVIDERS=github,google`。
运行经过身份验证的服务器：
```sh
make run
# 或
go run -buildvcs=false ./cmd/intervals-mcp
```
端点：
- MCP：`/mcp`
- OAuth同意：`/oauth/consent`
- OAuth保护的资源元数据：`/.well-known/oauth-protected-resource`
- 健康检查：`/healthz`
- 就绪检查：`/readyz`
## Fly.io
`fly.example.toml`是跟踪的可重用配置。将其复制到忽略的`fly.toml`以进行部署：
```sh
cp fly.example.toml fly.toml
```
编辑`fly.toml`以包含您的实际应用名称、区域和`MCP_PUBLIC_URL`。
将凭证存储为秘密：
```sh
fly secrets set -a your-real-app-name \
INTERVALS_ICU_API_KEY=... \
INTERVALS_ICU_ATHLETE_ID=... \
SUPABASE_URL=... \
SUPABASE_ANON_KEY=... \
OIDC_ALLOWED_EMAIL=...
```
使用以下命令部署：
```sh
fly deploy -c fly.toml
```
获取日志和状态：
```sh
fly status -a your-real-app-name
fly logs -a your-real-app-name
```
## 配置参考
配置采用dotenv样式。恰好选择一个配置文件，按以下顺序：
1. 显式`--env PATH`（必须存在；如果文件丢失则会报错）；
2. `$XDG_CONFIG_HOME/intervals-mcp/config.env`或`~/.config/intervals-mcp/config.env`；
3. 用于开发的本地`.env`仓库。
文件源不合并：如果存在XDG配置文件，则不会读取本地`.env`仓库。然后，非空进程环境变量覆盖所选文件，因此它们实际上具有最高的优先级。
`intervals config init`创建具有`0600`模式的配置文件。`config show`和`config doctor`会编辑秘密密钥，但会以纯文本打印非秘密标识符（运动员ID、邮箱、Supabase URL）- 在将其粘贴到问题或日志之前，请擦除其输出。
每个模式都需要：
- `INTERVALS_ICU_API_KEY`：Intervals.icu API密钥。
- `INTERVALS_ICU_ATHLETE_ID`：Intervals.icu运动员ID。
- `INTERVALS_ICU_BASE_URL`：可选，默认为`https://intervals.icu`。
需要经过身份验证的远程MCP：
- `MCP_PUBLIC_URL`：部署此服务器的公共HTTPS源。
- `SUPABASE_URL`和`SUPABASE_ANON_KEY`：Supabase项目值。
`SUPABASE_PUBLISHABLE_KEY`也被接受为别名。
- `OIDC_ALLOWED_EMAIL`或`OIDC_ALLOWED_SUBJECT`：允许访问配置的Intervals.icu运动员的单个Supabase身份。
- `MCP_REQUIRED_SCOPE`：可选。留空以使用Supabase OAuth服务器，除非您已验证发行的访问令牌包含所需的范围声明。
`SUPABASE_OAUTH_PROVIDERS`默认为空。仅为Supabase项目中启用的社交提供者设置逗号分隔列表。
## 开发
使用Go 1.26.3或`go.mod`中声明的版本。
```sh
make fix
make fmt
make check
```
`make check`运行非突变的格式化程序检查、`go vet`、竞争测试和`golangci-lint run`，因此它期望`golangci-lint`已安装。
GitHub Actions在推送和拉取请求上运行相同的非突变检查。
## 隐私
Intervals.icu活动、健康、恢复和日历数据可能很敏感。
不要提交真正的`.env`文件、API密钥、Supabase令牌、JWT、授权头、截图或包含个人数据的日志。
## 许可证
MIT。参见`LICENSE`。
