intervals-mcp

Intervals Extra（intervals-mcp）

一个面向单用户的远程 MCP 服务，用于获取和分析 intervals.icu 运动数据，并提供交互式 MCP Apps。

所有文本工具和每个 MCP App 都会直接与 intervals.icu 通信，并已通过真实账户验证；完整目录请参阅 docs/tools.md。配置会在启动时检查：变量无效时，服务会停止运行并指出变量名称；/health 会报告密钥是否存在。

历史。 本项目最初名为 strava-mcp，之后将数据源迁移到 intervals.icu；目前服务中没有任何功能会与 Strava 通信。

设置

1. 获取 intervals.icu API 密钥

1. 登录 intervals.icu
2. 前往 Settings（设置）中的 Developer Settings（开发者设置）
3. 复制个人 API 密钥

2. 配置环境

cp .env.example .env

使用你的值编辑 .env：

INTERVALS_API_KEY=your_api_key

所有变量均列于 docs/operations.md。

3. 运行

本地开发（需要 Bun）：

bun install
bun run dev

Docker：

docker compose up -d

更想使用预构建镜像？拉取最新版本 ghcr.io/ljcl/intervals-mcp:latest（也可在 MCP registry 中找到，名称为 io.github.ljcl/intervals-mcp），并将 compose 中的 image: 指向它，而不是自行构建；你仍需提供自己的 API 密钥。:edge 跟踪尚未发布的 main。发布的镜像包含 SBOM／来源证明，可供验证；请参阅 operations.md。

GET /health 会报告服务是否存活，且不会消耗 intervals.icu API 请求；设置 MCP_AUTH_TOKEN 后，还会报告配置和速率限制状态。响应格式和监控指南：operations.md。

将任何客户端指向 http://localhost:3000/mcp。仓库布局、任务运行器、测试、覆盖率门槛和 Storybook 工作流请参阅 docs/development.md。Agent 规范见 AGENTS.md。

连接 AI 工具

大多数 AI 工具（Claude Desktop、Claude Code 等）需要 HTTPS URL 才能访问你的 MCP 服务。由于服务运行在本地网络中，你需要使用隧道将其暴露出来。

Tailscale Funnel（推荐）

Tailscale Funnel 无需配置，即可通过 HTTPS 将本地端口暴露到互联网：

tailscale funnel --bg 3000
# → https://your-machine.tail1234.ts.net

在 .env 中将 PUBLIC_URL 设置为生成的 URL。

Cloudflare Tunnel

cloudflared tunnel --url http://localhost:3000

保护端点安全

隧道会使任何发现 URL 的人都能访问 /mcp，从而使用服务上配置的 intervals.icu API 密钥（密钥本身不会暴露给他们）。将 MCP_AUTH_TOKEN 设置为较长的随机密钥（openssl rand -hex 32），这样每个 /mcp 请求都必须包含 Authorization: Bearer <token>；下方的客户端配置片段均展示了应在何处添加此请求头。该密钥也用于限制对 /health 详细信息的访问。完整说明：operations.md。

在 .env 中与 API 密钥一起设置；docker-compose.yml 会自动转发该值。

AI Tool (Claude Desktop, Claude Code, etc.)
    │  HTTPS
HTTPS Tunnel (Tailscale / Cloudflare)
    │  HTTP (localhost:3000)
intervals-mcp Server (Docker / Bun)
    │  HTTPS
intervals.icu API

客户端配置

此服务适用于任何支持 Streamable HTTP 传输的 MCP 客户端。在下方的每个配置片段中，将 https://your-public-url 替换为你的隧道 URL（本地开发时可替换为 http://localhost:3000），并且仅在设置了 MCP_AUTH_TOKEN 时添加 Authorization 请求头。

Claude Desktop

将以下内容添加到 Claude 配置文件中 （macOS 上的路径为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "intervals-mcp": {
      "type": "url",
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

重启 Claude Desktop 以加载新配置。

Claude Code

claude mcp add --transport http intervals-mcp https://your-public-url/mcp \
  --header "Authorization: Bearer your-mcp-auth-token"

Cursor

添加到项目中的 .cursor/mcp.json（或添加到 ~/.cursor/mcp.json，以供所有项目使用）：

{
  "mcpServers": {
    "intervals-mcp": {
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

VS Code

添加到工作区中的 .vscode/mcp.json（或从命令面板运行 MCP: Add Server）：

{
  "servers": {
    "intervals-mcp": {
      "type": "http",
      "url": "https://your-public-url/mcp",
      "headers": { "Authorization": "Bearer your-mcp-auth-token" }
    }
  }
}

其他客户端（通用 Streamable HTTP）

任何支持 Streamable HTTP 的客户端都可以直接连接 /mcp 端点。该端点提供 2026-07-28 版协议：客户端发送无状态请求，其中包含 io.modelcontextprotocol/* 封装键和 Mcp-Method/Mcp-Name 标头（server/discover 用于公布功能）。由于 claude.ai 会以这种方式加载 MCP Apps，因此 2025 年版客户端（通过 initialize 发起连接的客户端）也能以无状态方式获得服务，但无法使用写入工具：update-activity、update-wellness 和 update-gear 需要 2026-07-28 版客户端。发送 POST JSON-RPC 消息时，请带上 Accept: application/json, text/event-stream 标头。协议详情请参阅：docs/architecture.md。

工具

完整的工具目录、提示词、权限行为和请求示例见 docs/tools.md。所有文本工具及每个 MCP App 的数据处理器都会直接与 intervals.icu 通信。

文档

文档	内容
docs/tools.md	完整的工具目录、提示词、权限行为和请求示例
docs/operations.md	环境变量、API 密钥、健康检查端点、速率限制、端点安全
docs/architecture.md	服务架构：传输、HTTP 层、缓存、错误分类、分析计算
docs/api-notes.md	调用 intervals.icu API：身份验证、端点、第 1 和第 2 阶段验证的行为
docs/mcp-apps.md	MCP App 软件包：共享外壳、移动端、主题设置、各 App 详情
docs/development.md	Monorepo 机制：Turborepo、覆盖率门槛、Storybook 门槛、Docker 构建
docs/releasing.md	发布自动化：Conventional Commit PR 标题、release-please、发布
docs/project.md	问题跟踪和项目看板
docs/Intervals_MCP_Server.md	功能参考文档，可作为项目知识上传到使用此服务的 Claude 项目中

PR 会以压缩合并的方式合并，且 PR 标题会成为 main 上的提交，因此请使用 Conventional Commit 格式（fix: 表示补丁版本，feat: 表示次版本，任何 ! 或 BREAKING CHANGE: 页脚表示主版本；chore:/docs:/refactor:/ci: 不会触发发布）。CI 检查会拒绝不符合规范的标题；请参阅 docs/releasing.md。

故障排除

服务在启动时退出： 消息会指出需要修正的变量，每个错误变量占一行。请参阅 operations.md。

AI 工具无法连接到服务 — MCP 要求使用 HTTPS URL。使用隧道（Tailscale Funnel 或 Cloudflare Tunnel）将本地服务开放到公网。请参阅连接到 AI 工具。

API 密钥错误： 先检查 /health：api_key_configured 会告知服务是否已设置密钥。如果 api_key_configured 为 true，但调用仍然失败，则密钥可能有误或已被撤销；请定期在 intervals.icu 的 Settings、Developer Settings 中生成新密钥，并更新 INTERVALS_API_KEY。请参阅 operations.md。

缺少今天的训练记录，或日期相差一天： 检查 /health 中的 time_zone 和 time_zone_source。如果未设置 TZ（或设为 UTC），服务会使用你的 intervals.icu 时区；设置 TZ 可选择时区。请参阅 operations.md。

“Cloudflare … answered with a challenge”： intervals.icu 前面的 Cloudflare 在请求到达 intervals.icu 之前就将其拦截了，因此这不是 API 密钥问题。请等待几分钟后重试。请参阅 operations.md。

客户端无法连接（401 或不支持的协议版本）： 每个被拒绝的 /mcp 请求都会在服务日志中写入一行 mcp_rejected，其中包含状态、JSON-RPC 代码，以及客户端发送时附带的名称。401 表示 bearer token 缺失或错误。代码 -32022 表示客户端信封中指定了服务不支持的 MCP 修订版本。请参阅 operations.md。

服务是否正在运行且可访问？ curl https://your-public-url/health。该请求不会访问 intervals.icu API，因此即使速率限制已耗尽也能正常使用。

授予读取工具权限后，客户端仍反复要求授权 — 某个版本可能重命名了工具或更改了其输入架构；授权按工具身份存储，因此这些更改会导致授权失效。版本说明会注明此类更改。否则，权限持久化由客户端负责 — 请检查连接器级和每个工具的设置。请参阅 docs/tools.md。

许可证

MIT