Coros MCP Server

A powerful Model Context Protocol (MCP) server that provides seamless access to your Coros watch data through AI assistants like Claude Desktop and Gemini CLI.

---

⚠️ IMPORTANT DISCLAIMER

🚨 THIS IS AN UNOFFICIAL APPLICATION

This MCP server uses unofficial, reverse-engineered Coros API endpoints that are not publicly documented or officially supported by Coros.

Use at your own risk:

• ❌ Not endorsed or supported by Coros
• ❌ API endpoints may change without notice
• ❌ Your account could potentially be affected
• ❌ No guarantees of functionality or data accuracy

By using this software, you acknowledge these risks and agree that the authors are not responsible for any issues that may arise.

---

💡 Inspiration & Credits

This project was inspired by and built upon the excellent work of:

• strava-mcp by @r-huijts - MCP server architecture and OAuth flow patterns
• coros-api by @xballoy - Coros API endpoint research and implementation

Special thanks to these projects for paving the way! 🙏

---

🌟 Features

• 🔐 Browser-Based Authentication - Secure login flow that opens in your browser
• 📊 8 Powerful Tools - Comprehensive access to all your Coros data
• 🏃 Activity Data - Recent activities, detailed metrics, lap-by-lap analysis
• 💪 EvoLab Metrics - Fitness scores, training status, recovery data
• 📅 Training Calendar - View scheduled workouts and training plans
• ❤️ Training Zones - Heart rate and pace zone information
• 🌤️ Weather Data - Environmental conditions for outdoor activities
• 📈 Time-Series Data - 1Hz GPS and biometric data for deep analysis

📋 Table of Contents

• Installation
• Quick Start
• Available Tools
• MCP Client Integration
• Usage Examples
• API Endpoints
• Development
• Troubleshooting
• Security
• License

🚀 Installation

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn
• A Coros account with activity data

Install Globally

# 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

After installation, the coros-mcp-server command will be available globally.

Verify Installation

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

⚡ Quick Start

1. Configure Your MCP Client

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

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

For Gemini CLI:

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

2. Restart Your MCP Client

Close and reopen Claude Desktop or restart Gemini CLI.

3. First-Time Authentication

In your AI assistant, simply say:

"Login to my Coros account"

The server will:

1. ✅ Open your browser to http://localhost:8111
2. ✅ Display a login form
3. ✅ Save your credentials securely to ~/.config/coros-mcp/credentials.json

After logging in, tell the assistant:

"I'm logged in"

You're ready to use all the tools!

🛠️ Available Tools

1. login

Start the authentication process by opening a web browser.

Parameters: None

Example:

"Login to my Coros account"

---

2. get_recent_activities

Get a list of recent Coros activities.

Parameters:

• limit (optional): Maximum number of activities (default: 20)
• sportTypes (optional): Filter by sport types (e.g., ["103"] for runs)
• fromDate (optional): Start date in ISO format
• toDate (optional): End date in ISO format

Example:

"Show me my last 10 runs"

---

3. get_activity_file_url

Get download URL for activity files in FIT, TCX, or GPX format.

Parameters:

• labelId (required): Activity ID
• sportType (required): Sport type number
• fileType (required): "fit", "tcx", or "gpx"

Example:

"Get the FIT file for activity 474723165319233737"

---

4. get_profile

Get user profile including training zones.

Parameters: None

Returns:

• Personal metrics (height, weight, age, sex)
• Heart rate zones (5-6 zones with ranges)
• Pace zones (lactate threshold pace)

Example:

"What are my heart rate training zones?"

---

5. get_evolab_metrics

Get EvoLab fitness and recovery data.

Parameters: None

Returns:

• Running fitness scores (endurance, threshold, speed, sprint)
• Training status (base fitness, load impact, intensity trend)
• Recovery data (percentage and remaining time)
• Efficiency trends (7-day scores)

Example:

"Show me my EvoLab fitness scores and recovery status"

---

6. get_training_calendar

Get training schedule for a date range.

Parameters:

• startDate (required): Start date in YYYYMMDD format
• endDate (required): End date in YYYYMMDD format

Returns: Scheduled workouts, rest days, completion status

Example:

"What workouts are scheduled for this week?"

---

7. get_sport_types

Get a mapping of all supported sport types.

Parameters: None

Returns: Dictionary of sport type IDs to names (e.g., 103: "Run")

Example:

"What sport types are available?"

---

8. get_activity_details

Get comprehensive activity analysis.

Parameters:

• labelId (required): Activity ID
• sportType (required): Sport type number

Returns:

• Summary metrics (distance, HR, power, cadence, calories, training load)
• Training effect (aerobic/anaerobic), VO2 Max, efficiency
• Lap-by-lap data with advanced metrics
• 1Hz time-series data (GPS + biometrics)
• Zone distribution (HR/pace/power)
• Weather conditions
• Advanced running metrics (ground contact time, vertical stride ratio)

Example:

"Show me detailed metrics for my last run including lap splits and heart rate zones"

🔧 MCP Client Integration

Claude Desktop

1. Edit config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add server configuration:

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

3. Restart Claude Desktop

Gemini CLI

1. Add to your Gemini CLI configuration
2. Restart Gemini CLI

MCP Inspector (for testing)

npx @modelcontextprotocol/inspector coros-mcp-server

Opens a web interface at http://localhost:6274 for interactive testing.

💡 Usage Examples

Training Zone Analysis

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

Fitness Tracking

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

Activity Analysis

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

Training Planning

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

🌐 API Endpoints

The server communicates with the following Coros API endpoints:

Endpoint	Method	Purpose
/account/login	POST	Authentication
/activity/query	GET	List activities
/activity/detail/query	POST	Detailed activity data
/activity/detail/download	POST	File download URLs
/profile/private/query	POST	User profile & zones
/analyse/query	POST	EvoLab metrics
/training/schedule/query	POST	Training calendar
/activity/fit/getImportSportList	GET	Sport type mappings

Base URLs:

• America: https://teamapi.coros.com
• Europe: https://teameuapi.coros.com
• China: https://teamcnapi.coros.com

👨‍💻 Development

Project Structure

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

Build Commands

# 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

Testing

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

# Test individual API calls
npm run debug

Adding New Tools

1. Add method to src/lib/coros-client.ts
2. Define tool schema in src/index.ts tools array
3. Add handler in the switch statement
4. Update this README
5. Build and test

🔍 Troubleshooting

Command Not Found

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

Authentication Issues

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

# Login again through the browser

Port Already in Use

The auth server uses port 8111. If it's in use:

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

MCP Inspector Not Working

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

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

API Errors

Common errors and solutions:

• "Not authenticated" - Run the login tool first
• "Service exceptions" - Activity ID might be invalid or too old
• "Invalid credentials" - Check email/password, try logging in again
• Network errors - Check internet connection and API region

Debug Mode

# Run debug script to test API calls
npm run debug

# Check MCP server logs
# Logs are written to stderr

🔒 Security

Credential Storage

• Credentials are stored in ~/.config/coros-mcp/credentials.json
• File permissions are set to 600 (owner read/write only)
• Password is MD5 hashed before transmission (Coros API requirement)

Authentication Flow

1. User initiates login through MCP tool
2. Browser opens to http://localhost:8111 (local only)
3. User enters credentials in browser
4. Credentials are tested against Coros API
5. If successful, saved to local config file
6. Access token obtained and cached in memory

Security Notes

⚠️ Important:

• This uses an unofficial Coros API
• Credentials are stored locally on your machine
• The auth server only runs on localhost
• No data is sent to third parties
• Use at your own risk

Best Practices

• Don't share your credentials.json file
• Use a strong, unique password for your Coros account
• Regularly update the MCP server
• Review the code before running if security is a concern

📄 License

MIT License - see LICENSE file for details

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

🙏 Acknowledgments

• Model Context Protocol by Anthropic
• Coros for their fitness tracking platform
• The MCP community for tools and inspiration

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🗺️ Roadmap

• [ ] Add caching for frequently accessed data
• [ ] Support for token refresh
• [ ] Export data to common formats
• [ ] Workout analysis and recommendations
• [ ] Integration with other fitness platforms
• [ ] Web dashboard for data visualization

---

Made with ❤️ for the Coros and MCP communities