Intervals.icu MCP 服务器

用于将 Claude 和 ChatGPT 与 Intervals.icu API 相连的模型上下文协议 (MCP) 服务器。它提供用于活动、赛事、健康数据、功率曲线和自定义项目身份验证及数据检索的工具。

如果您发现模型上下文协议 (MCP) 服务器很有用，请考虑捐赠以支持其持续开发。

环境要求

• Python 3.12 或更高版本

• 模型上下文协议 (MCP) Python SDK

• httpx

• python-dotenv

Related MCP server: Intervals.icu MCP Server

设置

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 Key

1. 登录您的 Intervals.icu 账户

2. 转到 设置 > API

3. 生成新的 API 密钥

查找您的运动员 ID

您的运动员 ID 通常会在您登录 Intervals.icu 后的网址中显示，如下所示：

• 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。

对于 Windows 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 中，打开 设置 → 功能 → 自定义 MCP 连接器 并点击 添加。填写以下内容：

   • 名称：Intervals.icu

   • MCP 服务器 URL：https://<您的公共主机>/sse

   • 身份验证：除非您已保护隧道，否则保持 无身份验证。

   您可以在此处复用相同的 ngrok http 8765 隧道 URL；只需确保它转发到您导出的主机/端口即可。

3. 保存连接器并打开一个新对话。ChatGPT 将保持 SSE 连接打开，并将后续请求 POST 到服务器发布的 /messages/ 接口。如果重新启动 MCP 服务器或隧道，请重新运行 SSE 命令，并在 URL 更改时更新连接器的 URL。

开发和测试

安装开发依赖并运行测试套件，请执行以下操作：

uv sync --all-extras
pytest -v tests

本地运行服务器

要手动启动服务器（在开发或测试时非常有用），请运行：

mcp run src/intervals_mcp_server/server.py

启用调试日志记录

要捕获服务器日志以进行调试，请将命令包装在 shell 中并将 stderr 重定向到文件中。

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