# Strava MCP Server ⚡

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
[![Strava API](https://img.shields.io/badge/Strava-API%20v3-orange.svg)](https://developers.strava.com/)

A comprehensive **Model Context Protocol (MCP)** server that provides full access to the **Strava API v3**. Perfect for integrating Strava data with Claude Desktop and other MCP-compatible clients.

## ✨ Features

### 🏃‍♂️ **Activities**
- Create and update manual activities
- Retrieve detailed activity information
- Access comments, kudos, laps, and power zones
- Search and filter activities with advanced parameters
- Upload GPX/TCX files

### 👤 **Athletes** 
- Get authenticated athlete profile and stats
- Access training zones and settings
- Update athlete profile information
- Retrieve athlete's club memberships

### 🏆 **Clubs**
- Browse club details and activities
- Access member lists and administrators
- Get club-specific activity feeds

### 🎯 **Segments & Routes**
- Explore segments in specific areas
- Access starred segments and leaderboards
- Get segment efforts and achievements
- Retrieve route details and export formats

### 🔧 **Additional Features**
- **40+ API endpoints** with full Strava API v3 coverage
- **OAuth 2.0 authentication** with automatic token management
- **Thread-safe operations** for reliable concurrent access
- **Comprehensive error handling** with detailed logging
- **MCP-compliant** tools and resources classification

## 🚀 Quick Start

### Prerequisites
- Python 3.8 or higher
- Strava Developer Account
- Claude Desktop or other MCP client

### Installation

1. **Clone the repository**
   ```bash
   git clone https://github.com/yourusername/strava-mcp.git
   cd strava-mcp
   ```

2. **Create virtual environment**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Set up Strava API credentials**
   - Go to [Strava Developers](https://developers.strava.com/)
   - Create a new application
   - Set Authorization Callback Domain to: `localhost`
   - Set Authorization Callback URL to: `http://localhost:8080`
   - Note your `Client ID` and `Client Secret`

5. **Complete setup (Recommended - All users)**
   ```bash
   python setup_complete.py
   ```
   This single script will:
   - Guide you through OAuth setup
   - Save tokens to `.env` file  
   - Automatically update your Claude Desktop config
   
   **Alternative setups for specific use cases:**
   ```bash
   # For server deployments (no Claude Desktop):
   python -m mcp_server.oauth_setup
   
   # For token refresh only (when tokens expire):
   python update_claude_config.py
   ```

6. **Configure Claude Desktop (if not auto-updated)**
   Add to your `claude_desktop_config.json`:
   ```json
   {
     "mcpServers": {
       "strava-mcp": {
         "command": "path/to/your/strava-mcp/start_mcp_server.bat",
         "cwd": "path/to/your/strava-mcp"
       }
     }
   }
   ```

## 🔧 Usage

### Manual Token Refresh
When your tokens expire, refresh them:
```bash
# Refresh tokens and update Claude Desktop config
python update_claude_config.py

# Or just refresh tokens in .env file
python refresh_tokens.py
```

### Available Tools & Resources

#### 🛠️ **Tools** (Write Operations)
- `create_strava_activity` - Create manual activities
- `update_strava_activity` - Update existing activities  
- `update_athlete_profile` - Update athlete information
- `star_strava_segment` - Star/unstar segments
- `upload_activity_file` - Upload GPX/TCX files
- `search_activities` - Advanced activity search
- `explore_segments_in_area` - Find segments by location
- `get_segment_leaderboard` - Get segment rankings
- `get_activity_stream_data` - Get activity stream data

#### 📊 **Resources** (Read Operations)
- Activity details, comments, kudos, laps, zones
- Athlete profile, stats, zones, clubs
- Club details, activities, members
- Gear information and usage stats
- Route details and export formats
- Segment information and efforts
- Stream data (GPS, power, heart rate)

## 🔐 Authentication

This server uses **OAuth 2.0** with manual token refresh:
- Secure token storage in environment variables
- Thread-safe token management
- Automatic Claude Desktop config updates
- Manual refresh capability for full control

## 📁 Project Structure

```
strava-mcp/
├── mcp_server/
│   ├── __init__.py
│   ├── __main__.py          # MCP server entry point
│   ├── server.py            # FastMCP server with tools/resources
│   ├── api.py              # Complete Strava API v3 wrapper
│   ├── auth.py             # OAuth 2.0 authentication manager
│   └── oauth_setup.py      # Initial OAuth setup utility
├── requirements.txt         # Python dependencies
├── refresh_tokens.py       # Manual token refresh utility
├── update_claude_config.py # Claude Desktop config updater
├── start_mcp_server.bat   # Server startup script (Windows)
├── start_mcp_server.sh    # Server startup script (Unix/Linux)
└── README.md              # This file
```

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- [Strava](https://www.strava.com/) for their comprehensive API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the standard
- [FastMCP](https://github.com/jlowin/fastmcp) for the server framework

## ⭐ Star this repo!

If you find this project useful, please consider giving it a star! It helps others discover this tool.