Metadata-Version: 2.4
Name: strava-activity-mcp-server
Version: 1.0.4
Summary: Strava MCP server with secure token handling and summary-first analytics
Project-URL: Homepage, https://github.com/BojanMakivic/strava-activity-mcp-server
Project-URL: Documentation, https://github.com/BojanMakivic/strava-activity-mcp-server/blob/main/README.md
Project-URL: Source, https://github.com/BojanMakivic/strava-activity-mcp-server
Project-URL: Changelog, https://github.com/BojanMakivic/strava-activity-mcp-server/blob/main/CHANGELOG.md
Author: Bojan Makivic
Maintainer: Bojan Makivic
License-Expression: GPL-3.0-or-later
License-File: LICENSE
Keywords: analytics,fitness,mcp,model-context-protocol,strava
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: mcp[cli]>=1.16.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: build>=1.3.0; extra == 'dev'
Requires-Dist: twine>=6.2.0; extra == 'dev'
Requires-Dist: ty>=0.0.14; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Provides-Extra: security
Requires-Dist: bandit>=1.7.10; extra == 'security'
Requires-Dist: pip-audit>=2.7.0; extra == 'security'
Description-Content-Type: text/markdown

# Strava Activity MCP Server
![Python Package](https://github.com/tomekkorbak/strava-mcp-server/actions/workflows/python-package.yml/badge.svg)
![PyPI - Version](https://img.shields.io/pypi/v/strava-activity-mcp-server)
[![License: GNU](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://opensource.org/licenses/gpl-3-0)
[![Python 3.13](https://img.shields.io/badge/python-3.13-blue?logo=python&logoColor=white)](https://www.python.org/downloads/release/python-3130/)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/strava-activity-mcp-server)](https://pypistats.org/packages/strava-activity-mcp-server)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/strava-activity-mcp-server?period=total&units=NONE&left_color=GRAY&right_color=GREEN&left_text=total_downloads)](https://pepy.tech/projects/strava-activity-mcp-server)

![image](https://raw.githubusercontent.com/BojanMakivic/strava-activity-mcp-server/7b2cc0b43575c7f7724a8fa0cf8be67c40e3ed17/ref/image.jpg)



A small Model Context Protocol (MCP) server that exposes your Strava athlete data to language-model tooling.

After the first browser-based authorization, the server uses the saved `refresh_token` to automatically refresh your session; no further URL-redirected logins are required on subsequent runs.

This package provides a lightweight MCP server which communicates with the Strava API and exposes a few helper tools (authorization URL, token exchange/refresh, and fetching athlete activities) that language models or other local tools can call.

The project is intended to be used locally (for example with Claude MCP integrations) and is published on PyPI as `strava-activity-mcp-server`.

## Installation

Install from PyPI with pip (recommended inside a virtual environment):

```powershell
pip install strava-activity-mcp-server
```

## Requirements

- Python >= 3.10 (see `pyproject.toml`)
- The package depends on `mcp[cli]` and `requests` (installed from PyPI).

## Quick start

After installing, you can run the MCP server using the provided console script or by importing and calling `main()`.

Run via the console script (entry point defined in `pyproject.toml`):

```cmd
strava-activity-mcp-server
```

Or, from Python:

```python
from strava_activity_mcp_server import main
main()
```

By default the server starts the MCP runtime; when used with an MCP-aware client (for example Msty MCP orsome other MCP integrations such Claude, LM Tool and etc.) the exposed tools become callable.

## Authentication (Strava OAuth)

This server requires Strava OAuth credentials to access athlete data. You will need:

- STRAVA_CLIENT_ID
- STRAVA_CLIENT_SECRET

Steps:

1. Create a Strava API application at https://www.strava.com/settings/api and note your Client ID and Client Secret. Use `localhost` as the Authorization Callback Domain.
2. Initial authorization: call the `strava.auth.url` tool to generate an authorization URL (see IMAGE below), open it in your browser, and grant access. This step is only needed the first time to obtain an authorization code.

   ![auth](https://github.com/user-attachments/assets/a348ccc7-a4be-49fb-8f79-b88f9d80cfc9)

3. Copy the `code` from the redirected URL (Image below). Use the provided tools to exchange it for access/refresh tokens.

   ![code](https://github.com/user-attachments/assets/0bb54edb-c9f9-4416-8fb2-c7e0a38d11c9)


4. After the initial authorization, a token file named `strava_mcp_tokens.json` is created and stored in your home directory (for example on Windows: `C:\\Users\\<YourUserName>\\strava_mcp_tokens.json`). This file contains your `refresh_token`, which will be used automatically for subsequent logins. After the first authorization you do not need to open the browser flow again; future runs refresh the access token from the locally stored `refresh_token`.

### Recommended credential setup on Windows (simple and persistent)

To avoid putting real credentials in MCP client JSON files, set your credentials once as Windows user environment variables:

1. Open Start and search for: `Edit environment variables for your account`
2. Under **User variables**, create:
  - `STRAVA_CLIENT_ID` = your numeric client ID (digits only, no quotes)
  - `STRAVA_CLIENT_SECRET` = your client secret
3. Fully restart your MCP client (for example Msty) so it picks up the new variables.

PowerShell alternative (one-time setup):

```powershell
[Environment]::SetEnvironmentVariable("STRAVA_CLIENT_ID", "YOUR_ID_HERE", "User")
[Environment]::SetEnvironmentVariable("STRAVA_CLIENT_SECRET", "YOUR_SECRET_HERE", "User")
```

Notes:
- Do not include surrounding quotes in the saved value (for example store `12345`, not `"12345"`).
- `STRAVA_CLIENT_ID` must be an integer value; otherwise tools return: `STRAVA_CLIENT_ID must be an integer`.




## Exposed Tools (what the server provides)

The MCP server exposes the following tools (tool IDs shown). These map to functions in `src/strava_activity_mcp_server/strava_activity_mcp_server.py` and cover both initial authorization and subsequent refresh flows.

Canonical tool IDs use dot notation (for example `strava.auth.url`). URI-style aliases (for example `strava://auth/url`) are kept for backwards compatibility.

- `strava.auth.url` (alias: `strava://auth/url`) — Build the Strava OAuth authorization URL.
  - Inputs: `client_id` (int, optional; reads `STRAVA_CLIENT_ID` if omitted)
  - Output: Authorization URL string
- `strava.auth.refresh` (alias: `strava://auth/refresh`) — Refresh tokens using a refresh token and persist them locally.
  - Inputs: `refresh_token` (str), `client_id` (int, optional), `client_secret` (str, optional)
  - Output: sanitized status only (token values are not returned)
- `strava.athlete.stats` (alias: `strava://athlete/stats`) — Exchange an authorization `code` for tokens and then fetch one page of recent activities.
  - Inputs: `code` (str), `client_id` (int, optional), `client_secret` (str, optional), `after` (int, optional), `before` (int, optional), `page` (int, optional), `per_page` (int, optional)
  - Output: `{ activities, token_status, save }` (token values redacted)
- `strava.athlete.stats-with-token` (alias: `strava://athlete/stats-with-token`) — Fetch one page of recent activities using an existing access token.
  - Inputs: `access_token` (str), `after` (int, optional), `before` (int, optional), `page` (int, optional), `per_page` (int, optional)
  - Output: Activity list (JSON)
- `strava.auth.save` (alias: `strava://auth/save`) — Save tokens to `~\strava_mcp_tokens.json`.
  - Inputs: `tokens` (dict)
  - Output: `{ ok, path }` or error
- `strava.auth.load` (alias: `strava://auth/load`) — Load tokens from `~\strava_mcp_tokens.json`.
  - Inputs: none
  - Output: `{ ok, path, token_status }` or error (token values redacted)
- `strava.athlete.refresh-and-stats` (alias: `strava://athlete/refresh-and-stats`) — Load saved refresh token, refresh access token, save it, and fetch one page of activities.
  - Inputs: `client_id` (int, optional), `client_secret` (str, optional), `after` (int, optional), `before` (int, optional), `page` (int, optional), `per_page` (int, optional)
  - Output: `{ activities, token_status }` (token values redacted)
- `strava.session.start` (alias: `strava://session/start`) — Convenience entry: if tokens exist, refresh and fetch; otherwise return an auth URL to begin initial authorization.
  - Inputs: `client_id` (int, optional), `client_secret` (str, optional), `after` (int, optional), `before` (int, optional), `page` (int, optional), `per_page` (int, optional)
  - Output: Either refreshed activity payload with `token_status` metadata, or `{ auth_url, token_file_checked }`

- `strava.athlete.fetch-all` (alias: `strava://athlete/fetch-all`) — Fetch all pages deterministically.
  - Inputs: `access_token` (optional), `after` (optional), `before` (optional), `per_page` (default `50`), `max_pages` (default `10`), `retry_count` (default `2`), `detail_level` (`summary` default, or `detailed`), `detail_max_rows` (capped)
  - Stop behavior: iterates until page size is `< per_page` or `max_pages` is reached.
  - Output (default): compact summary + meta; detailed rows only when explicitly requested.

These tools are intended to be called by MCP clients.

- `strava.trimp.banister` — Fetch all athlete activities (paged), filter to activities with heart-rate, compute Banister TRIMP, and rank variability.
  - Alias: `strava://trimp/account-report`
  - Inputs: `sex` (male/female), `hr_rest`, `hr_max`, optional paging (`per_page`, `max_pages`) and filters (`after`, `before`), plus `detail_level` (`summary` default, or `detailed`) and `detail_max_rows` (capped)
  - Output (default): compact TRIMP summary and sport variability; detailed `activities` rows are only included in explicit detailed mode.

## Activity Filtering

The server now supports advanced filtering for Strava activities through URL parameters. The following filter parameters are available for activity-related tools:

- **`after`** (int, optional): An epoch timestamp to filter activities that have taken place after a certain time
- **`before`** (int, optional): An epoch timestamp to filter activities that have taken place before a certain time  
- **`page`** (int, optional): The page number of activities to retrieve (default=1)
- **`per_page`** (int, optional): Number of activities per page (max=200)
  - Default values: `strava.athlete.stats` uses 30; analytics flows default to 50 for safer LLM context usage.

### Filtering Examples

- Get activities from the last 30 days: `after=1640995200` (epoch timestamp for Jan 1, 2022)
- Get activities from a specific date range: `after=1640995200&before=1643673600`
- Get the first 10 activities: `page=1&per_page=10`
- Get activities from page 2 with 50 per page: `page=2&per_page=50`

These filters work with the following tools:
- `strava.athlete.stats` / `strava://athlete/stats`
- `strava.athlete.stats-with-token` / `strava://athlete/stats-with-token`
- `strava.athlete.refresh-and-stats` / `strava://athlete/refresh-and-stats`
- `strava.session.start` / `strava://session/start`
- `strava.athlete.fetch-all` / `strava://athlete/fetch-all`

## Example flows

1) Get an authorization URL and retrieve tokens

- Call `strava.auth.url` (or `strava://auth/url`) with your `client_id` and open the returned URL in your browser.
- After authorizing, Strava will provide a `code`.

2) Fetch recent activities

- Use `strava.athlete.stats` for single-page activity retrieval. If the access token is expired, use the refresh flow to get a new access token.

3) Fetch filtered activities

- Get activities from the last 7 days: Use `strava.athlete.stats-with-token` with `after` parameter set to epoch timestamp
- Get paginated results: Use `page` and `per_page` parameters to control the number of activities returned
- Get activities from a specific date range: Combine `after` and `before` parameters

4) Fetch all pages reliably

- Use `strava.athlete.fetch-all` for full-history retrieval.
- For analytics/reporting over all activities (including Banister TRIMP), prefer this high-level tool or `strava.trimp.banister` which now uses deterministic pagination internally.

### Client config example and quick inspector test

Any MCP-capable client can launch the server using a config similar to the following (example file often called `mcp.json` or `config.json`).

Recommended for Msty on Windows: keep real credentials out of the JSON file and rely on Windows user environment variables.

```json
{
  "command": "uvx",
  "args": [
    "strava-activity-mcp-server"
  ]
}
```

If your MCP client supports environment-variable interpolation, this pattern may also work:

```json
{
  "command": "uvx",
  "args": [
    "strava-activity-mcp-server"
  ],
  "env": {
    "STRAVA_CLIENT_ID": "${STRAVA_CLIENT_ID}",
    "STRAVA_CLIENT_SECRET": "${STRAVA_CLIENT_SECRET}"
  }
}
```

If interpolation is not supported by your MCP client, it may pass the literal text `${STRAVA_CLIENT_ID}` and `${STRAVA_CLIENT_SECRET}`. In that case, remove the `env` block and rely on inherited Windows user variables.

To quickly test the server using the Model Context Protocol inspector tool, run:

```powershell
npx @modelcontextprotocol/inspector uvx strava-activity-mcp-server
```

This will attempt to start the server with the `uvx` transport and connect the inspector to the running MCP server instance named `strava-activity-mcp-server`.

## Chat example using MCP in Msty Studio

![chat_1](https://github.com/user-attachments/assets/460cced5-15b3-41eb-9805-72966826ede8)
![chat_2](https://github.com/user-attachments/assets/9ded03f3-0f86-400e-8ebc-c414d0346257)
![chat_3](https://github.com/user-attachments/assets/d793c9a5-8fb2-430e-a0bf-679903cf3f97)
![chat_4](https://github.com/user-attachments/assets/4a459c31-3b42-4c32-8685-e6dd851dadca)


## Contributing

Contributions are welcome. Please open issues or pull requests that include a clear description and tests where applicable.

## License

This project is licensed under the GNU GENERAL PUBLIC LICENSE — see the `LICENSE` file for details.

## Links

- Source: repository root
- Documentation note: see `README.md` for an example MCP configuration
- Changelog: see `CHANGELOG.md` for last changes








