Corus MCP

合唱团MCP服务器

一个强大的 模型上下文协议（MCP） 服务器，通过Claude Desktop和Gemini CLI等人工智能助手无缝访问您的Coros手表数据。

______________________________________________________________________

⚠️ 重要免责声明

🚨 这是一个非官方应用程序 此MCP服务器使用 非官方的反向发动机Coros API端点 Coros没有公开记录或官方支持。 使用风险自负： - ❌ 未得到Coros的认可或支持 - ❌ API端点可能会更改，恕不另行通知 - ❌ 您的帐户可能会受到影响 - ❌ 不保证功能或数据准确性 使用本软件即表示您承认这些风险，并同意作者不对可能出现的任何问题负责。

______________________________________________________________________

💡 灵感与信用

该项目的灵感来自并建立在以下优秀工作的基础上：

特别感谢这些项目为我们铺平了道路！ 🙏

______________________________________________________________________

🌟 特性

• 🔐 基于浏览器的身份验证 -在浏览器中打开的安全登录流
• 📊 8强大的工具 -全面访问您的所有Coros数据
• 🏃 活动数据 -近期活动、详细指标、逐圈分析
• 💪 EvoLab指标 -体能评分、训练状态、恢复数据
• 📅 培训日历 -查看已安排的锻炼和训练计划
• ❤️ 培训区 -心率和配速区信息
• 🌤️ 天气数据 -户外活动的环境条件
• 📈 时间序列数据 -1Hz GPS和生物特征数据用于深度分析

📋 目录

• 安装
• 快速开始
• 可用工具
• MCP客户端集成
• 使用示例
• API终点
• 发展
• 故障排除
• 安全
• 许可证

🚀 安装

先决条件

• Node.js 18.0.0或更高版本
• npm或纱线
• 包含活动数据的Coros帐户

全球安装

# Clone the repository
git clone https://github.com/yourusername/coros-mcp-server.git
cd coros-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Install globally
npm link

安装后 coros-mcp-server 命令将在全球范围内可用。

验证安装

which coros-mcp-server
# Should output: /path/to/node/bin/coros-mcp-server

⚡ 快速开始

1.配置您的MCP客户端

适用于克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "coros": {
      "command": "coros-mcp-server"
    }
  }
}

适用于Gemini CLI:

{
  "mcpServers": {
    "coros": {
      "command": "coros-mcp-server"
    }
  }
}

2.重新启动MCP客户端

关闭并重新打开Claude Desktop或重新启动Gemini CLI。

3.首次身份验证

在您的AI助手中，只需说：

“登录我的Coros帐户”

服务器将：

1. ✅ 打开浏览器http://localhost:8111
2. ✅ 显示登录表单
3. ✅ 将您的凭据安全地保存到 ~/.config/coros-mcp/credentials.json

登录后，告诉助手：

“我已登录”

你已经准备好使用所有的工具了！

🛠️ 可用工具

1. login

打开web浏览器启动身份验证过程。

参数： 无

例子：

“登录我的Coros帐户”

______________________________________________________________________

2. get_recent_activities

获取Coros最近的活动列表。

参数：

• limit （可选）：最大活动数（默认值：20）
• sportTypes （可选）：按运动类型筛选（例如，跑步时为\[“103”\]）
• fromDate （可选）：ISO格式的开始日期
• toDate （可选）：ISO格式的结束日期

例子：

“显示我最近的10次跑步”

______________________________________________________________________

3. get_activity_file_url

获取FIT、TCX或GPX格式的活动文件的下载URL。

参数：

• labelId （必填）：活动ID
• sportType （必填）：运动类型编号
• fileType （必填）：“fit”、“tcx”或“gpx”

例子：

“获取活动474723165319233737的FIT文件”

______________________________________________________________________

4. get_profile

获取包括培训区在内的用户资料。

参数： 无

退货：

• 个人指标（身高、体重、年龄、性别）
• 心率区域（5-6个带范围的区域）
• 起搏区（乳酸阈值起搏）

例子：

“我的心率训练区是什么？”

______________________________________________________________________

5. get_evolab_metrics

获取EvoLab健康和恢复数据。

参数： 无

退货：

• 跑步体能得分（耐力、阈值、速度、冲刺）
• 训练状态（基础体能、负荷冲击、强度趋势）
• 恢复数据（百分比和剩余时间）
• 效率趋势（7天评分）

例子：

“显示我的EvoLab健康评分和恢复状态”

______________________________________________________________________

6. get_training_calendar

获取日期范围内的培训计划。

参数：

• startDate （必填）：YYYYMMDD格式的开始日期
• endDate （必填）：YYYYMMDD格式的结束日期

退货： 计划锻炼、休息日、完成状态

例子：

“本周计划进行哪些锻炼？”

______________________________________________________________________

7. get_sport_types

获取所有支持的运动类型的映射。

参数： 无

退货： 运动类型ID到名称的词典（例如，103：“Run”）

例子：

“有哪些运动类型可供选择？”

______________________________________________________________________

8. get_activity_details

获得全面的活动分析。

参数：

• labelId （必填）：活动ID
• sportType （必填）：运动类型编号

退货：

• 总结指标（距离、心率、功率、节奏、卡路里、训练负荷）
• 训练效果（有氧/无氧）、最大摄氧量、效率
• 具有高级指标的逐圈数据
• 1Hz时间序列数据（GPS+生物识别）
• 区域分布（人力资源/速度/功率）
• 天气情况
• 高级跑步指标（地面接触时间、垂直步幅比）

例子：

“显示我上一次跑步的详细指标，包括分圈和心率区域”

🔧 MCP客户端集成

克劳德桌面版

1. 编辑配置文件：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

1. 添加服务器配置：

{
  "mcpServers": {
    "coros": {
      "command": "coros-mcp-server"
    }
  }
}

1. 重新启动克劳德桌面

Gemini CLI

1. 添加到Gemini CLI配置
2. 重新启动Gemini CLI

MCP检查员（用于测试）

npx @modelcontextprotocol/inspector coros-mcp-server

在以下位置打开web界面http://localhost:6274用于交互式测试。

💡 使用示例

训练区分析

User: "What are my current heart rate zones?"
Assistant: [Uses get_profile]
Response:
- Zone 1 (Recovery): 120-135 bpm
- Zone 2 (Aerobic): 135-150 bpm
- Zone 3 (Tempo): 150-165 bpm
- Zone 4 (Threshold): 165-175 bpm
- Zone 5 (VO2 Max): 175+ bpm

健身追踪

User: "How's my fitness and recovery?"
Assistant: [Uses get_evolab_metrics]
Response:
- Endurance: 85/100
- Recovery: 78% (5 hours remaining)
- Training Load: Optimal

活动分析

User: "Analyze my last run with lap splits"
Assistant: [Uses get_recent_activities, then get_activity_details]
Response: Detailed breakdown including:
- Overall stats (distance, pace, HR)
- Lap-by-lap splits
- Heart rate zone distribution
- Weather conditions

培训计划

User: "What workouts are scheduled for next week?"
Assistant: [Uses get_training_calendar]
Response: List of scheduled workouts with dates and types

🌐 API终点

服务器与以下Coros API端点进行通信：

基本URL：

• 美国： https://teamapi.coros.com
• 欧洲： https://teameuapi.coros.com
• 中国 https://teamcnapi.coros.com

👨‍💻 发展

项目结构

coros-mcp-server/
├── src/
│   ├── index.ts                 # MCP server entry point
│   ├── lib/
│   │   ├── coros-client.ts      # Coros API client
│   │   ├── config-manager.ts    # Credential storage
│   │   ├── auth-server.ts       # Browser-based auth
│   │   └── types.ts             # TypeScript types
│   ├── config-server.ts         # Alternative config UI
│   └── auth-server.ts           # Standalone auth server
├── scripts/
│   └── debug-coros.ts           # Debug/testing script
├── dist/                        # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

构建命令

# Install dependencies
npm install

# Build TypeScript
npm run build

# Start MCP server (for testing)
npm start

# Run in development mode
npm run dev

# Debug Coros API calls
npm run debug

# Open browser-based auth
npm run auth

# Open alternative config UI
npm run config

测试

# Test with MCP Inspector
npx @modelcontextprotocol/inspector coros-mcp-server

# Test individual API calls
npm run debug

添加新工具

1. 添加方法 src/lib/coros-client.ts
2. 在中定义工具架构 src/index.ts 工具阵列
3. 在switch语句中添加处理程序
4. 更新此自述文件
5. 构建和测试

🔍 故障排除

未找到命令

# Re-link the package
cd /path/to/coros-mcp-server
npm link

身份验证问题

# Delete saved credentials
rm ~/.config/coros-mcp/credentials.json

# Login again through the browser

端口已在使用中

身份验证服务器使用端口8111。如果正在使用：

# Find and kill the process
lsof -ti:8111 | xargs kill -9

MCP检查员不工作

# Kill any running instances
pkill -f coros-mcp-server
pkill -f inspector

# Start fresh
npx @modelcontextprotocol/inspector coros-mcp-server

API错误

常见错误及解决方法：

• “未通过身份验证” -先运行登录工具
• “服务例外” -活动ID可能无效或太旧
• “凭据无效” -检查电子邮件/密码，尝试重新登录
• 网络错误 -检查互联网连接和API区域

调试模式

# Run debug script to test API calls
npm run debug

# Check MCP server logs
# Logs are written to stderr

🔒 安全

凭据存储

• 凭据存储在 ~/.config/coros-mcp/credentials.json
• 文件权限设置为 600 （仅限所有者读/写）
• 密码在传输前进行MD5哈希（Coros API要求）

身份验证流程

1. 用户通过MCP工具启动登录
2. 浏览器打开到http://localhost:8111（仅限本地）
3. 用户在浏览器中输入凭据
4. 根据Coros API测试证书
5. 如果成功，则保存到本地配置文件
6. 获取访问令牌并将其缓存在内存中

安全说明

⚠️ 重要提示：

• 这使用了一个非官方的Coros API
• 凭据存储在本地计算机上
• 身份验证服务器仅在本地主机上运行
• 不向第三方发送数据
• 使用风险自负

最佳实践

• 不要分享你的 credentials.json 文件
• 为您的Coros帐户使用强大、唯一的密码
• 定期更新MCP服务器
• 如果担心安全性，请在运行前检查代码

📄 许可证

MIT许可证-请参阅 许可证 详细信息文件

🤝 贡献

欢迎投稿！拜托：

1. 克隆该仓库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

🙏 致谢

• 模型上下文协议 通过Anthropic
• Coros健身跟踪平台
• MCP社区提供工具和灵感

📞 支持

• 问题:
• 讨论:

🗺️ 路线图

• \[\]为频繁访问的数据添加缓存
• \[\]支持令牌刷新
• \[\]将数据导出为通用格式
• \[\]锻炼分析和建议
• \[\]与其他健身平台整合
• \[\]用于数据可视化的Web仪表板

______________________________________________________________________

由...制作❤️ Coros和MCP社区