Intervals.icu MCP Server

Intervals.icu MCP 服务

用于通过模型上下文协议（MCP）将 Claude 和 ChatGPT 连接到 Intervals.icu API 的 MCP 服务。它提供用于身份验证以及检索活动、事件、健康数据、功率曲线和自定义项目的工具。

如果您觉得这个模型上下文协议（MCP）服务有用，请考虑捐款支持其持续开发。

要求

• Python 3.12 或更高版本
• 模型上下文协议（MCP）Python SDK
• httpx
• python-dotenv

设置

1. 安装 uv（推荐）

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

安装后，找到 uv 的完整路径——稍后配置 Claude Desktop 时需要用到：

where.exe uv
# Example output: C:\Users\<USERNAME>\.local\bin\uv.exe

2. 克隆此仓库

git clone https://github.com/mvilanova/intervals-mcp-server.git
cd intervals-mcp-server

3. 创建并激活虚拟环境

# Create virtual environment with Python 3.12
uv venv --python 3.12

# Activate virtual environment
# On macOS/Linux:
source .venv/bin/activate
# On Windows:
.venv\Scripts\activate

4. 同步项目依赖项

uv sync

5. 设置环境变量

运行以下命令，复制 .env.example 并将其命名为 .env：

macOS/Linux：

cp .env.example .env

Windows（PowerShell）：

Copy-Item .env.example .env

然后编辑 .env 文件，设置您的 Intervals.icu 运动员 ID 和 API 密钥：

API_KEY=your_intervals_api_key_here
ATHLETE_ID=your_athlete_id_here

获取 Intervals.icu API 密钥

1. 登录您的 Intervals.icu 账户
2. 前往“设置”>“API”
3. 生成新的 API 密钥

查找您的运动员 ID

登录 Intervals.icu 后，通常可以在 URL 中看到您的运动员 ID。格式如下：

• https://intervals.icu/athlete/i12345/...，其中 i12345 是您的运动员 ID

更新

此项目正在积极开发中，会定期添加新功能和修复。要保持最新状态，请按以下步骤操作：

1. 从 main 拉取最新更改

⚠️ 运行此命令前，请确保没有未提交的更改。

macOS/Linux：

git checkout main && git pull

Windows（PowerShell）：

git checkout main; git pull

2. 更新 Python 依赖项

激活虚拟环境并同步依赖项：

macOS/Linux：

source .venv/bin/activate
uv sync

Windows（PowerShell）：

.venv\Scripts\activate
uv sync

故障排除

如果 Claude Desktop 因配置更改而无法运行，请按以下步骤操作：

1. 删除 claude_desktop_config.json 中现有的 Intervals.icu 条目。
2. 在 intervals-mcp-server 目录中重新配置 Claude Desktop。

macOS/Linux：

mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env

Windows： 按照 Windows 配置部分中的说明手动重新添加该条目。

常见错误

spawn uv ENOENT — Claude Desktop 找不到 uv 可执行文件。请在 command 字段中使用 uv 的完整路径。运行 which uv（macOS/Linux）或 where.exe uv（Windows）获取路径。

Windows 上出现 spawn /Users/... ENOENT — 配置文件中包含 macOS/Linux 格式的路径。请按照下文 Windows 配置部分中的说明，将其替换为正确的 Windows 路径，并使用反斜杠。

Windows Store 安装：配置更改未生效 — 您可能编辑了错误的配置文件。从 Microsoft Store 安装的 Claude Desktop 会读取 AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json，而不是 AppData\Roaming\Claude\。

与 Claude 搭配使用

1. 配置 Claude Desktop

要将此服务与 Claude Desktop 搭配使用，需要将其添加到 Claude Desktop 配置中。

macOS/Linux

1. 在 intervals-mcp-server 目录中运行以下命令，配置 Claude Desktop：

mcp install src/intervals_mcp_server/server.py --name "Intervals.icu" --with-editable . --env-file .env

2. 打开 Claude Desktop 的配置文件 claude_desktop_config.json 后，内容应如下所示：

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "/Users/<USERNAME>/.local/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "/path/to/intervals-mcp-server",
        "mcp",
        "run",
        "/path/to/intervals-mcp-server/src/intervals_mcp_server/server.py"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

其中 /path/to/ 是系统中 intervals-mcp-server 代码文件夹的路径。

Windows

由于环境或权限问题，mcp install 命令在 Windows 上可能会失败。请改为手动配置 Claude Desktop：

1. 找到 Claude Desktop 配置文件。如果 Claude Desktop 是从 Microsoft Store 安装的，配置文件位于：

   C:\Users\<USERNAME>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json
   

   如果通过标准安装程序安装，配置文件可能位于：

   C:\Users\<USERNAME>\AppData\Roaming\Claude\claude_desktop_config.json
   

   如果文件或文件夹不存在，请创建它。

2. 将以下条目添加到 claude_desktop_config.json，并将占位符替换为实际值：

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "C:\\Users\\<USERNAME>\\.local\\bin\\uv.exe",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with-editable",
        "C:\\path\\to\\intervals-mcp-server",
        "mcp",
        "run",
        "C:\\path\\to\\intervals-mcp-server\\src\\intervals_mcp_server\\server.py"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

• JSON 中所有 Windows 路径都使用双反斜杠（\\）。
• 要查找 uv.exe 的完整路径，请在 PowerShell 中运行 where.exe uv。
• 要查找克隆仓库的完整路径，请在 intervals-mcp-server 文件夹中运行 pwd。

Microsoft Store 安装说明： 从 Microsoft Store 安装的 Claude Desktop 会将配置隔离在 AppData\Local\Packages\... 下。编辑 AppData\Roaming\Claude\claude_desktop_config.json 不会产生任何效果——请确保编辑正确的文件。

3. 重启 Claude Desktop。

2. 将 MCP 服务与 Claude 搭配使用

服务运行且 Claude Desktop 配置完成后，你可以使用以下工具查询过去和未来的活动、事件及健康数据。

• get_activities：检索活动列表
• get_activity_details：获取指定活动的详细信息
• get_activity_intervals：获取指定活动的详细间歇数据
• get_activity_streams：获取指定活动的原始数据流（功率、心率等）
• get_athlete_power_curves：获取所选时长和时间段内的最佳功率曲线
• get_wellness_data：获取健康数据
• get_events：检索即将到来的事件（训练、比赛等）
• get_event_by_id：获取指定事件的详细信息
• add_or_update_event：创建或更新事件（训练、比赛、备注等）
• delete_event：删除指定事件
• delete_events_by_date_range：删除指定日期范围内的事件
• get_custom_items：获取运动员的自定义项目（图表、自定义字段、区域等）
• get_custom_item_by_id：获取指定自定义项目的详细信息
• create_custom_item：为运动员创建自定义项目
• update_custom_item：更新现有自定义项目
• delete_custom_item：删除自定义项目

与 ChatGPT 搭配使用

ChatGPT 的 Beta 版 MCP 连接器也可以通过 SSE 传输与此服务通信。

1. 以 SSE 模式启动服务，使其公开 /sse 和 /messages/ 端点：

   export FASTMCP_HOST=127.0.0.1 FASTMCP_PORT=8765 MCP_TRANSPORT=sse FASTMCP_LOG_LEVEL=INFO
   python src/intervals_mcp_server/server.py
   

   启动日志会显示完整 URL（例如 http://127.0.0.1:8765/sse）。ChatGPT 需要此公共 URL，因此如果没有直接公开服务，请使用 ngrok http 8765 等工具转发端口。

2. 在 ChatGPT 中，打开 Settings → Features → Custom MCP Connectors，然后点击 Add。填写以下内容：

   • Name：Intervals.icu
   • MCP Server URL：https://<your-public-host>/sse
   • Authentication：除非你已保护隧道，否则保留为 No authentication。

   你可以在此处重复使用同一个 ngrok http 8765 隧道 URL；只需确保它转发到上文公开的主机和端口。

3. 保存连接器并打开新聊天。ChatGPT 会保持 SSE 连接，并向服务公布的 /messages/ 端点 POST 后续请求。如果重启 MCP 服务或隧道，请重新运行 SSE 命令；如果连接器 URL 有变化，也请更新它。

开发与测试

安装开发依赖并运行测试套件：

uv sync --all-extras
pytest -v tests

在本地运行服务

要手动启动服务（适用于开发或测试），请运行：

mcp run src/intervals_mcp_server/server.py

启用调试日志

若要捕获服务日志以进行调试，请在 Shell 中包装命令，并将标准错误重定向到文件。

macOS/Linux — 按如下方式修改 claude_desktop_config.json：

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "/Users/<USERNAME>/.local/bin/uv run --with 'mcp[cli]' --with-editable /path/to/intervals-mcp-server mcp run /path/to/intervals-mcp-server/src/intervals_mcp_server/server.py 2>> /path/to/intervals-mcp-server/mcp-server.log"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

然后跟踪日志文件，即可实时查看输出：

tail -f /path/to/intervals-mcp-server/mcp-server.log

Windows — 按如下方式修改 claude_desktop_config.json：

{
  "mcpServers": {
    "Intervals.icu": {
      "command": "powershell",
      "args": [
        "-Command",
        "C:\\Users\\<USERNAME>\\.local\\bin\\uv.exe run --with 'mcp[cli]' --with-editable C:\\path\\to\\intervals-mcp-server mcp run C:\\path\\to\\intervals-mcp-server\\src\\intervals_mcp_server\\server.py 2>> C:\\path\\to\\intervals-mcp-server\\mcp-server.log"
      ],
      "env": {
        "INTERVALS_API_BASE_URL": "https://intervals.icu/api/v1",
        "ATHLETE_ID": "<YOUR_ATHLETE_ID>",
        "API_KEY": "<YOUR_API_KEY>",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

然后使用 PowerShell 实时监视日志文件：

Get-Content C:\path\to\intervals-mcp-server\mcp-server.log -Wait

许可证

GNU 通用公共许可证 v3.0

精选

Glama.ai