# Coros MCP Server

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

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)

---

## ⚠️ 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](https://github.com/r-huijts/strava-mcp)** by [@r-huijts](https://github.com/r-huijts) - MCP server architecture and OAuth flow patterns
- **[coros-api](https://github.com/xballoy/coros-api)** by [@xballoy](https://github.com/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](#installation)
- [Quick Start](#quick-start)
- [Available Tools](#available-tools)
- [MCP Client Integration](#mcp-client-integration)
- [Usage Examples](#usage-examples)
- [API Endpoints](#api-endpoints)
- [Development](#development)
- [Troubleshooting](#troubleshooting)
- [Security](#security)
- [License](#license)

## 🚀 Installation

### Prerequisites

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

### Install Globally

```bash
# 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

```bash
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`):

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

**For Gemini CLI**:

```json
{
  "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:

```json
{
  "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)

```bash
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

```bash
# 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

```bash
# 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

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

### Authentication Issues

```bash
# 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:

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

### MCP Inspector Not Working

```bash
# 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

```bash
# 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](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](https://modelcontextprotocol.io) by Anthropic
- Coros for their fitness tracking platform
- The MCP community for tools and inspiration

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/coros-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/coros-mcp-server/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**