### Run on the fly with `uvx` (No git clone required)
You can run the server directly from the repository without cloning it manually by using `uvx`. `uv` will download it into a temporary isolated environment and execute it:
```bash
# Set up your .env file in the current directory first!
*(If you are already inside the cloned directory, you can also just run `uvx --from . strava-mcp`)*
---
---
## Strava API Setup
## Strava API Setup
@@ -69,90 +91,36 @@ uvx strava-mcp-server
3. Set **Authorization Callback Domain** to `localhost`
3. Set **Authorization Callback Domain** to `localhost`
4. Note your **Client ID** and **Client Secret**
4. Note your **Client ID** and **Client Secret**
### 2. Generate Your OAuth Tokens
### 2. Configure Environment
The server uses the OAuth 2.0 refresh token flow. Run the token helper script to authorize and retrieve your initial tokens:
```bash
uv run strava-mcp-get-token
```
This will:
1. Open your browser with the Strava authorization page
2. Ask you to authorize the application
3. Automatically capture the authorization code
4. Exchange it for access and refresh tokens
5. Save the `STRAVA_REFRESH_TOKEN` to your `.env` file
> **Required OAuth Scopes:**
> `activity:read_all,profile:read_all,read`
>
> - `activity:read_all` — Access all activities including private ones
> - `profile:read_all` — Access full profile info including heart rate zones
> - `read` — Access public data
---
## Configuration
Copy the example environment file and fill in your credentials:
Copy the example environment file:
```bash
```bash
cp .env.example .env
cp .env.example .env
```
```
Edit `.env` and fill in your Client ID and Secret:
Edit `.env`:
```env
```env
STRAVA_CLIENT_ID=your_client_id_here
STRAVA_CLIENT_ID=your_client_id_here
STRAVA_CLIENT_SECRET=your_client_secret_here
STRAVA_CLIENT_SECRET=your_client_secret_here
STRAVA_REFRESH_TOKEN=your_refresh_token_here
```
```
> **Note:** The `STRAVA_REFRESH_TOKEN` is written automatically by `get_token.py`. You only need to fill in `STRAVA_CLIENT_ID` and `STRAVA_CLIENT_SECRET` manually.
### 3. Authenticate (The Magic Way ✨)
You **do not** need to manually fiddle with OAuth tokens. The server includes an interactive MCP tool to handle authentication!
1. Start the server (`docker run ...` or `uv run strava-mcp`).
2. Connect to the server via an MCP Client (like Claude Desktop or MCP Inspector).
3. Call the `get_new_oauth_token` MCP tool.
4. Your browser will open for you to authorize the app. The server will intercept the callback locally, generate your tokens, and automatically save the `STRAVA_REFRESH_TOKEN` to your `.env` file!
> **Required OAuth Scopes:**
> `activity:read_all,profile:read_all,read`
---
---
## Running the Server
## Connecting with MCP Clients
```bash
The server listens on **port 8000** by default and exposes an SSE endpoint:
uv run strava-mcp
`http://localhost:8000/mcp`
```
Expected output:
```
🚀 Starting Strava MCP Server on http://0.0.0.0:8000
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
```
The server listens on **port 8000** by default and exposes a single endpoint:
```
http://localhost:8000/mcp
```
### Stopping the Server
Press `Ctrl+C` for a clean shutdown. If the port is already in use from a previous run:
```bash
lsof -ti :8000 | xargs kill -9
```
---
## Connecting with MCP Inspector
1. Open [MCP Inspector](https://inspector.modelcontextprotocol.io/) or run it locally
2. Select transport: **Streamable HTTP**
3. Enter URL: `http://localhost:8000/mcp`
4. Click **Connect**
> ⚠️ Make sure to use `http://localhost:8000/mcp` **without a trailing slash** and with the `Accept: application/json, text/event-stream` header (handled automatically by MCP clients).
### Claude Desktop
### Claude Desktop
@@ -169,99 +137,50 @@ Add to your `claude_desktop_config.json`:
}
}
```
```
### MCP Inspector
1. Open [MCP Inspector](https://inspector.modelcontextprotocol.io/)
2. Select transport: **Streamable HTTP**
3. Enter URL: `http://localhost:8000/mcp`
4. Click **Connect**
---
---
## MCP Primitives
## MCP Primitives
### Tools
### Tools
#### 🏃 Athlete
#### 🔐 Authentication
| Tool | Description |
|------|-------------|
| `get_new_oauth_token` | Starts the interactive browser OAuth2 flow to generate and save your initial Refresh Token |
| Tool | Parameters | Description |
#### 🏃 Athlete
|------|-----------|-------------|
| Tool | Description |
|`get_athlete_profile` | — | Full athlete profile: name, city, country, follower count, gear list |
|------|-------------|
| `get_athlete_stats` | — | Training totals: all-time, year-to-date, and last 4 weeks for runs, rides, and swims |
| `get_athlete_profile` | Full athlete profile: name, city, country, follower count, gear list |
| `get_athlete_zones` | — | Heart rate and power zones |
| `get_athlete_stats` | Training totals: all-time, year-to-date, and last 4 weeks for runs, rides, and swims |
| `get_athlete_zones` | Heart rate and power zones |
#### 🚴 Activities
#### 🚴 Activities
| Tool | Description |
|------|-------------|
| `list_activities` | Paginated activity list with optional time range filters |
| `get_activity_details` | Full activity details incl. segment efforts |
| `get_activity_laps` | Lap splits |
| `get_activity_zones` | Heart rate and power zones for a specific activity |
| `get_activity_comments` | Comments on an activity |
| `get_activity_kudoers` | Athletes who gave kudos |
| `get_activity_streams` | Raw GPS/sensor data streams |
| Tool | Parameters | Description |
*(Note: Additional tools exist for Clubs, Routes, Segments, Segment Efforts, and Gear. See MCP Inspector for full details.)*
|------|-----------|-------------|
| `list_activities` | `limit`, `page`, `before`*, `after`* | Paginated activity list with optional time range filters |
| `get_activity_details` | `activity_id` | Full activity details incl. segment efforts (IDs returned as strings) |
| `get_activity_laps` | `activity_id` | Lap splits |
| `get_activity_zones` | `activity_id` | Heart rate and power zones for a specific activity |
| `get_activity_comments` | `activity_id`, `limit` | Comments on an activity |
| `get_activity_kudoers` | `activity_id`, `limit` | Athletes who gave kudos |
| `get_activity_streams` | `activity_id`, `keys` | Raw GPS/sensor data streams |
> *`before` and `after` are Unix timestamps. Example: `after=1704067200` = since 2024-01-01.
#### 🏛️ Clubs
| Tool | Parameters | Description |
|------|-----------|-------------|
| `list_athlete_clubs` | `limit` | Clubs the athlete is a member of |
| `get_segment_effort` | `effort_id: str` | Details for a specific effort — requires Strava subscription |
| `list_segment_efforts` | `segment_id`, `start_date_local`, `end_date_local`, `limit` | Athlete's efforts on a segment — requires Strava subscription |
| `get_segment_effort_streams` | `effort_id: str`, `keys` | Raw streams for a segment effort — requires Strava subscription |
> ℹ️ **Effort IDs** must be copied as strings from `get_activity_details` response. Do not retype the numbers manually — they exceed JavaScript's safe integer range.
#### ⚙️ Gear
| Tool | Parameters | Description |
|------|-----------|-------------|
| `get_gear_by_id` | `gear_id: str` | Bike or shoe details: brand, model, total distance |
> Gear IDs start with `b` for bikes and `g` for shoes (e.g. `b12345678`). Find them in `get_activity_details` under `gear_id`.
### Prompts
### Prompts
Prompts pre-structure AI conversations with the right tool-calling instructions.
Prompts pre-structure AI conversations with the right tool-calling instructions.
#### `analyze_activity`
- **`analyze_activity`**: Triggers a structured analysis of a specific activity including summary, performance metrics, and key takeaways.
- **`training_summary`**: Generates a training load report for the last N weeks (volume, trends, recommendations).
```
Parameters: activity_id (str)
```
Triggers a structured analysis of a specific activity including summary, performance metrics, segment highlights, gear used, and key takeaways.
#### `training_summary`
```
Parameters: weeks (int, default: 4)
```
Generates a training load report for the last N weeks: volume by sport, highlights, trend vs. year-to-date, and recommendations. Automatically calculates the required Unix timestamp for filtering.
---
---
@@ -269,33 +188,41 @@ Generates a training load report for the last N weeks: volume by sport, highligh
> **Workaround for segment efforts:** Use `get_activity_details` to access segment efforts embedded in activity data. The `segment_efforts[]` array contains effort IDs, times, heart rate, power, and PR/KOM ranks.
> **Workaround for segment efforts:** Use `get_activity_details` to access segment efforts embedded in activity data. The `segment_efforts[]` array contains effort IDs, times, heart rate, power, and PR/KOM ranks.
@@ -305,44 +232,17 @@ The following endpoints are **restricted by Strava** and return errors for regul
## Troubleshooting
## Troubleshooting
### `[Errno 48] Address already in use`
### `[Errno 48] Address already in use`
Port 8000 is occupied by a previous server process:
Port 8000 is occupied by a previous server process:
If you are developing locally on macOS and your `strava-mcp-server` directory is located inside `Documents/` or `Desktop/`, **iCloud Drive** will constantly sync and delete files inside your virtual environment (`.venv`), leading to missing packages.
**Solution:** Move the project out of iCloud or rename the folder to end in `.nosync` (e.g. `strava-mcp-server.nosync`).
Your refresh token has expired or been rotated. Generate a new one:
### 401 Unauthorized
Your refresh token has expired or been revoked. Simply run the `get_new_oauth_token` MCP tool again to re-authenticate!
```bash
uv run strava-mcp-get-token
```
### Empty results from `list_segment_efforts`
The direct Strava endpoint is restricted. Access segment efforts via `get_activity_details` instead — the full activity response includes all segment efforts.
### `406 Not Acceptable` from MCP endpoint
The MCP client is missing the required `Accept: application/json, text/event-stream` header. Use a proper MCP client (MCP Inspector, Claude Desktop) instead of raw `curl`.
### Route or effort `404 Not Found` with a large ID
The ID was truncated due to JavaScript float precision. Always use the **string IDs** returned by the server — never copy-type large numeric IDs manually.
---
## Tech Stack
| Component | Library |
|-----------|---------|
| MCP Server | [FastMCP](https://github.com/jlowin/fastmcp) |
| HTTP Transport | Uvicorn + Starlette (via FastMCP) |
| Strava API Client | [httpx](https://www.python-httpx.org/) |
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
