intervals-icu-mcp

Intervals.icu MCP 服务

用于集成 Intervals.icu 的 Model Context Protocol（MCP）服务。通过 Claude、ChatGPT 和其他大模型访问训练数据、健康指标和表现分析。

最初基于 eddmann/intervals-icu-mcp（采用 MIT 许可）。本项目是独立的后续项目，修复了大量错误并加入了新功能，详情请参阅 CHANGELOG.md。

概览

共 69 个工具，涵盖活动、活动分析、活动消息、运动员资料、健康状况、赛事/日历、表现曲线、训练计划库、装备、运动设置和自定义项目；此外还有 4 个 MCP 资源（运动员资料、训练计划语法、赛事类别、自定义项目架构）和 9 个 MCP 提示词（训练分析、恢复检查、每周规划等）。各类别的详细分类请参阅可用工具。

快速开始

或者，只需 30 秒即可在 Claude Desktop 中完成设置：

1. 获取你的 API 密钥和运动员 ID
2. 将以下内容添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

3. 重启 Claude，然后提问 “显示我过去 7 天的活动。”

想使用 Claude Code、Cursor 或 ChatGPT？请参阅客户端配置。想从源代码运行或使用 Docker？请参阅安装与设置。

前置条件

安装 uv——它能通过一个工具处理 Python、依赖项和执行。在 macOS/Linux 上运行 curl -LsSf https://astral.sh/uv/install.sh | sh（或运行 brew install uv；Homebrew 已不再为 Intel Mac 安装），在 Windows 上运行 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"。之后，uvx 会自动获取 Python 和软件包。如果 MCP 客户端找不到 uvx，请将 command 设置为 which uvx 输出的完整路径。也支持使用 Docker 作为替代方案。

Intervals.icu API 密钥设置

安装前，请获取 Intervals.icu API 密钥：

1. 前往 https://intervals.icu/settings → Developer → Create API Key。
2. 复制密钥，并从个人资料 URL 中记下你的运动员 ID（格式：i123456）。

安装与设置

如果使用推荐的设置，则无需单独安装任何内容。 uvx（随 uv 一起提供）会在 MCP 客户端首次启动时自动下载并缓存 intervals-icu-mcp 软件包——只需将客户端配置中的配置片段粘贴到客户端即可完成设置。

git clone https://github.com/hhopke/intervals-icu-mcp.git
cd intervals-icu-mcp
uv sync
uv run intervals-icu-mcp-auth  # interactive credential setup; or create .env manually:
#   INTERVALS_ICU_API_KEY=your_api_key_here
#   INTERVALS_ICU_ATHLETE_ID=i123456

docker build -t intervals-icu-mcp .

# Interactive credential setup (creates intervals-icu-mcp.env in the current directory):
touch intervals-icu-mcp.env  # pre-create the file so Docker mounts it as a file, not a dir
docker run -it --rm \
  -v "$(pwd)/intervals-icu-mcp.env:/app/.env" \
  --entrypoint= intervals-icu-mcp:latest \
  python -m intervals_icu_mcp.scripts.setup_auth

客户端配置

此服务通过 stdio 使用 MCP，可与任何兼容的客户端配合使用。点击客户端名称可展开。如果你按照快速开始（uvx）操作，请使用第一个配置块；如果使用了上面的源代码或 Docker 替代方案，请使用同一折叠区域中的对应配置。

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/intervals-icu-mcp", "intervals-icu-mcp"]
    }
  }
}

{
  "mcpServers": {
    "intervals-icu": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-v", "/ABSOLUTE/PATH/TO/intervals-icu-mcp.env:/app/.env", "intervals-icu-mcp:latest"]
    }
  }
}

claude mcp add intervals-icu --scope user \
  --env INTERVALS_ICU_API_KEY=your-key \
  --env INTERVALS_ICU_ATHLETE_ID=i123456 \
  -- uvx intervals-icu-mcp

{
  "mcpServers": {
    "intervals-icu": {
      "command": "uvx",
      "args": ["intervals-icu-mcp"],
      "env": {
        "INTERVALS_ICU_API_KEY": "your-api-key-here",
        "INTERVALS_ICU_ATHLETE_ID": "i123456"
      }
    }
  }
}

使用方法

用自然语言让 Claude 与你的 Intervals.icu 数据交互。以下是一些入门提示词：

"Show me my activities from the last 30 days"
"Am I overtraining? Check my CTL, ATL, and TSB"
"How's my recovery this week? Show HRV and sleep trends"
"Create a sweet spot cycling workout for tomorrow"
"What's my 20-minute power and FTP?"

按类别整理的完整示例提示词目录，请参阅 docs/examples.md。

可用工具

69 个工具、4 个资源和 9 个提示词模板。以下为一行摘要，完整参考请见 docs/tools.md。

删除安全模式

破坏性工具受可选环境变量 INTERVALS_ICU_DELETE_MODE（safe / full / none，默认值为 safe）控制。这是模型无法访问的服务端限制，因此无法调用未注册的工具。完整模式表、响应结构和 TZ 缓冲区的设计依据，请参阅 docs/tools.md。

远程部署（HTTP / SSE）

默认情况下，服务通过 stdio 运行，这是适用于 Claude Desktop、Claude Code 和 Cursor 等本地客户端的传输方式。HTTP 和 SSE 传输方式可用于远程或托管场景。

⚠️ MCP 没有内置身份验证——切勿在没有隧道（Tailscale、Cloudflare Tunnel）或带身份验证的反向代理的情况下，将 HTTP 模式的服务暴露在不可信网络中。

传输标志和完整安全模型请参阅 docs/remote-deployment.md。

文档

• 示例提示词 — 按类别整理的自然语言提示词完整目录
• 工具参考 — 完整的工具、资源和提示词清单
• 架构概览 — 介绍服务、中间件、客户端和工具如何协同工作
• 远程部署（HTTP/SSE） — 托管/远程部署的传输方式、标志和安全模型
• 测试指南 — pytest + respx 的惯例、夹具和测试套件运行方法
• 更新日志 — 发布历史
• 添加新工具 — 贡献者逐步操作指南

反馈

你是如何使用这个项目的？ 你常用哪些工具、提示词是什么样的、哪些地方会妨碍你——这些比我自己的猜测更能影响项目路线图。

展示与分享 · 问答 · 想法 · 综合讨论 — 也可以针对可复现的错误提交问题。

贡献

非常欢迎贡献，任何贡献都不嫌小——无论是修正拼写错误、改进参数说明、添加测试，还是开发全新工具。无需具备 Python 或 MCP 专业知识。请参阅 CONTRIBUTING.md；简而言之，提交 PR 前请运行 make can-release。适合新手的问题是一个轻松的起点。

赞助

本项目采用 MIT License 免费提供，我利用业余时间维护。如果它对你有帮助，GitHub Sponsors 可以支持项目持续开发——完全自愿；反馈或 PR 也同样有帮助。

许可证

MIT License — 详情请参阅 LICENSE 文件。

免责声明

本项目与 Intervals.icu 无关联，也未获得其认可或赞助。所有产品名称、徽标和品牌均为其各自所有者的财产。