# Strava MCP Server

A Model Context Protocol (MCP) server that integrates with the Strava API, allowing AI assistants to access your Strava fitness data.

## Features

- Fetch athlete profile and statistics
- List and query activities
- Access segment data and efforts
- Explore segments by geographic area
- View starred segments

## Prerequisites

- Node.js 18 or higher
- A Strava account
- Strava API credentials (Client ID and Client Secret)

## Installation

1. Clone this repository:
```bash
git clone https://github.com/juanlarreapm/strava-mcp-server.git
cd strava-mcp-server
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Strava API Setup

Before using this server, you need to create a Strava API application:

1. Go to [https://www.strava.com/settings/api](https://www.strava.com/settings/api)
2. Create a new application
3. Set the **Authorization Callback Domain** to `localhost`
4. Note your **Client ID** and **Client Secret**

## Getting OAuth Tokens

Run the authentication setup script to obtain your access tokens:

```bash
node setup-auth.cjs
```

This will:
1. Prompt you for your Client ID and Client Secret
2. Open a browser for Strava authorization
3. Display your access token, refresh token, and other credentials

Keep these credentials secure - you'll need them to configure the MCP server.

## Configuration

The server requires the following environment variables:

- `STRAVA_ACCESS_TOKEN` - Your Strava access token (required)
- `STRAVA_REFRESH_TOKEN` - Your refresh token (optional, for token renewal)
- `STRAVA_CLIENT_ID` - Your Strava application Client ID (optional)
- `STRAVA_CLIENT_SECRET` - Your Strava application Client Secret (optional)

### For Claude Desktop

Add this to your Claude Desktop MCP settings file:

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

```json
{
  "mcpServers": {
    "strava": {
      "command": "node",
      "args": ["/path/to/strava-mcp-server/dist/index.js"],
      "env": {
        "STRAVA_ACCESS_TOKEN": "your_access_token_here",
        "STRAVA_REFRESH_TOKEN": "your_refresh_token_here",
        "STRAVA_CLIENT_ID": "your_client_id_here",
        "STRAVA_CLIENT_SECRET": "your_client_secret_here"
      }
    }
  }
}
```

### For Other MCP Clients

Create a `.env` file in the project root (see `.env.example`):

```bash
STRAVA_ACCESS_TOKEN=your_access_token_here
STRAVA_REFRESH_TOKEN=your_refresh_token_here
STRAVA_CLIENT_ID=your_client_id_here
STRAVA_CLIENT_SECRET=your_client_secret_here
```

## Available Tools

The server exposes the following tools:

### `get_athlete_profile`
Get the authenticated athlete's profile information.

### `get_athlete_stats`
Get detailed statistics including totals and recent activity counts.

### `list_activities`
List recent activities with optional pagination and time filtering.

**Parameters:**
- `before` (number): Unix timestamp to get activities before this time
- `after` (number): Unix timestamp to get activities after this time
- `page` (number): Page number (default: 1)
- `per_page` (number): Items per page (default: 30, max: 200)

### `get_activity`
Get detailed information about a specific activity.

**Parameters:**
- `id` (string, required): The activity ID
- `include_all_efforts` (boolean): Include all segment efforts

### `get_segment`
Get information about a specific segment.

**Parameters:**
- `id` (string, required): The segment ID

### `list_starred_segments`
List segments starred by the athlete.

**Parameters:**
- `page` (number): Page number
- `per_page` (number): Items per page

### `explore_segments`
Explore segments in a geographic area.

**Parameters:**
- `bounds` (string, required): Coordinates as `sw_lat,sw_lng,ne_lat,ne_lng`
- `activity_type` (string): Either `running` or `riding`
- `min_cat` (number): Minimum climb category (0-5)
- `max_cat` (number): Maximum climb category (0-5)

### `get_segment_efforts`
Get efforts on a specific segment.

**Parameters:**
- `segment_id` (string, required): The segment ID
- `start_date_local` (string): ISO 8601 formatted start date
- `end_date_local` (string): ISO 8601 formatted end date
- `per_page` (number): Items per page

## Development

### Build
```bash
npm run build
```

### Watch mode
```bash
npm run watch
```

### Run locally
```bash
npm start
```

## Token Expiration

Strava access tokens expire after 6 hours. To handle token refresh:

1. Store your refresh token securely
2. Implement token refresh logic using the Strava OAuth token endpoint
3. Or run `setup-auth.cjs` again to get fresh tokens

## Rate Limits

Strava API has rate limits:
- 100 requests per 15 minutes
- 1000 requests per day

Plan your usage accordingly.

## Troubleshooting

### "STRAVA_ACCESS_TOKEN environment variable is required"
Make sure you've set the access token in your MCP configuration or environment variables.

### "Strava API error: 401"
Your access token may have expired. Run `setup-auth.cjs` to get a new token.

### "Authorization Callback Domain" error
Ensure you've set the callback domain to `localhost` in your Strava API settings.

## Contributing

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

## License

MIT License - see LICENSE file for details

## Resources

- [Strava API Documentation](https://developers.strava.com/docs/reference/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Strava API Settings](https://www.strava.com/settings/api)