# 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)
