291 lines
8.7 KiB
Markdown
291 lines
8.7 KiB
Markdown
# 🚴 Strava MCP Server
|
||
|
||
A production-ready **Model Context Protocol (MCP) server** that exposes the Strava API v3 as MCP-compatible tools, resources, and prompts — enabling AI agents and LLM-based applications to query your Strava training data through a standardized interface.
|
||
|
||
Built with [FastMCP](https://github.com/jlowin/fastmcp) and the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk), compatible with MCP Inspector, Claude Desktop, and any MCP-compliant client.
|
||
|
||
---
|
||
|
||
## ✨ Features
|
||
|
||
- 🛠️ **25+ MCP Tools** covering all major Strava API read endpoints (including athlete profile & stats)
|
||
- 💬 **2 MCP Prompts** for structured AI-driven training analysis
|
||
- 🔄 **Automated OAuth** — authentication flow via a standalone setup script with auto-rotation
|
||
- 🐳 **Multi-Arch Docker** — optimized builds for `linux/amd64` and `linux/arm64` powered by `uv`
|
||
- 🏷️ **Dynamic Versioning** — versions are automatically derived from Git tags (powered by `hatch-vcs`)
|
||
- 🤖 **Agent-First Design** — includes specific instructions for LLMs on handling European date formats (DD.MM.YYYY)
|
||
- 🌐 **Streamable HTTP transport** for broad client compatibility (SSE)
|
||
- 🔒 **Read-only** — no write operations, safe to use with AI agents
|
||
- 📝 **Design Decisions** — documented architectural choices in `docs/DESIGN_DECISIONS.md`
|
||
|
||
---
|
||
|
||
## 📋 Table of Contents
|
||
|
||
- [Requirements](#requirements)
|
||
- [Installation & Deployment](#installation--deployment)
|
||
- [Docker (Recommended)](#docker-recommended)
|
||
- [Local Python (uv)](#local-python-uv)
|
||
- [Strava API Setup](#strava-api-setup)
|
||
- [Connecting with MCP Clients](#connecting-with-mcp-clients)
|
||
- [MCP Primitives](#mcp-primitives)
|
||
- [Project Structure](#project-structure)
|
||
- [Design Decisions](#design-decisions)
|
||
- [CI/CD (Gitea Actions)](#cicd-gitea-actions)
|
||
- [Development & Testing](#️-development--testing)
|
||
- [Git Hooks](#git-hooks)
|
||
- [Known Strava API Limitations](#known-strava-api-limitations)
|
||
- [Troubleshooting](#troubleshooting)
|
||
|
||
---
|
||
|
||
## Requirements
|
||
|
||
- A [Strava account](https://www.strava.com) with API access
|
||
- A [Strava API Application](https://www.strava.com/settings/api)
|
||
- **Docker** (for containerized deployment) OR **Python 3.10+** & [uv](https://github.com/astral-sh/uv)
|
||
|
||
---
|
||
|
||
## Installation & Deployment
|
||
|
||
### Docker (Recommended)
|
||
|
||
The project includes a multi-arch Docker build (amd64/arm64).
|
||
|
||
```bash
|
||
# Clone the repository
|
||
git clone https://git.hnrx.net/hnrx/strava-mcp-server.git
|
||
cd strava-mcp-server
|
||
|
||
# Build the image locally
|
||
docker build -t strava-mcp-server:latest .
|
||
|
||
# Run the container (injecting your .env file)
|
||
docker run --rm -p 8000:8000 --env-file .env strava-mcp-server:latest
|
||
```
|
||
|
||
### Local Python (PyPI)
|
||
|
||
The easiest way to get started is using our **interactive onboarding wizard**. You don't even need to clone the repository:
|
||
|
||
```bash
|
||
# 1. Start the interactive setup wizard
|
||
uvx --from strava-mcp-server-hnrx auth
|
||
|
||
# 2. Run the MCP server
|
||
uvx --from strava-mcp-server-hnrx server
|
||
```
|
||
|
||
The wizard will guide you through creating a Strava API application and automatically save your credentials to a `.env` file.
|
||
|
||
### Installation
|
||
|
||
If you prefer a traditional installation:
|
||
|
||
```bash
|
||
pip install strava-mcp-server-hnrx
|
||
# or
|
||
uv add strava-mcp-server-hnrx
|
||
```
|
||
|
||
### Running from source
|
||
|
||
If you want to contribute or run the latest dev version:
|
||
|
||
```bash
|
||
git clone https://git.hnrx.net/hnrx/strava-mcp-server.git
|
||
cd strava-mcp-server
|
||
|
||
# Start the MCP server
|
||
uv run server
|
||
|
||
# Run the OAuth setup script
|
||
uv run auth
|
||
```
|
||
|
||
---
|
||
|
||
## Strava API Setup
|
||
|
||
### 1. 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 **Authorization Callback Domain** to `localhost`
|
||
4. Note your **Client ID** and **Client Secret**
|
||
|
||
### 2. Configure Environment
|
||
|
||
Copy the example environment file:
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
Edit `.env` and fill in your Client ID and Secret:
|
||
```env
|
||
STRAVA_CLIENT_ID=your_client_id_here
|
||
STRAVA_CLIENT_SECRET=your_client_secret_here
|
||
```
|
||
|
||
### 3. Authenticate (The Magic Way ✨)
|
||
|
||
The server is designed for zero-touch deployment. You can authorize it **after** it has started.
|
||
|
||
1. **Start the server** (it will log a warning that the refresh token is missing, but it will boot!).
|
||
2. **Run the Auth Script**:
|
||
- Run `uv run auth` in your terminal on your local machine.
|
||
3. Your browser will open. Log in and authorize.
|
||
4. **Success:** The browser will show you the exact values for your `.env` (or Kubernetes Secret). The script will also automatically update your local `.env` file!
|
||
|
||
---
|
||
|
||
## Connecting with MCP Clients
|
||
|
||
The server listens on **port 8000** and exposes an SSE endpoint: `http://localhost:8000/mcp`
|
||
|
||
### Claude Desktop
|
||
Add to `claude_desktop_config.json`:
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"strava": {
|
||
"url": "http://localhost:8000/mcp",
|
||
"transport": "streamable-http"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## MCP Primitives
|
||
|
||
### Tools
|
||
|
||
| Category | Tools |
|
||
|----------|-------|
|
||
| 🏃 **Athlete** | `get_athlete_profile`, `get_athlete_stats`, `get_athlete_zones` |
|
||
| 🚴 **Activities** | `list_activities`, `get_activity_details`, `get_activity_laps`, `get_activity_zones`, `get_activity_streams` |
|
||
| 🏘️ **Clubs** | `get_athlete_clubs`, `get_club_activities`, `get_club_members` |
|
||
|
||
---
|
||
|
||
## Design Decisions
|
||
|
||
For a detailed list of architectural choices, unit standardizations, and LLM-specific optimizations, please refer to:
|
||
👉 **[docs/DESIGN_DECISIONS.md](docs/DESIGN_DECISIONS.md)**
|
||
|
||
---
|
||
|
||
## CI/CD (Gitea Actions)
|
||
|
||
Our pipeline (`.gitea/workflows/cicd.yml`) is fully automated:
|
||
- **Linting:** Every push/PR is checked with `ruff`.
|
||
- **Multi-Arch Builds:** Builds `amd64` and `arm64` images simultaneously using QEMU and DinD.
|
||
- **Smart Tagging:**
|
||
- Pushes to `main` are tagged as `:latest`.
|
||
- Git Tags (e.g., `v1.2.0`) trigger a versioned build and **automatically update the Gitea Release description** with the correct `docker pull` command.
|
||
|
||
---
|
||
|
||
## Troubleshooting
|
||
|
||
### `[Errno 48] Address already in use`
|
||
`lsof -ti :8000 | xargs kill -9`
|
||
|
||
### 401 Unauthorized
|
||
Your token expired. Run `uv run auth` to refresh.
|
||
|
||
---
|
||
|
||
## 🛠️ Development & Testing
|
||
|
||
### 1. Local Testing with MCP Inspector
|
||
|
||
The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is the best way to test the server without a full LLM client.
|
||
|
||
**Option A: Test via STDIO (Fastest)**
|
||
This runs the server directly in your terminal (perfect for local debugging):
|
||
```bash
|
||
npx @modelcontextprotocol/inspector uv run server
|
||
```
|
||
|
||
**Option B: Test via SSE (Remote/Docker)**
|
||
If the server is already running (e.g., at `http://localhost:8000`):
|
||
1. Open [https://inspector.modelcontextprotocol.io/](https://inspector.modelcontextprotocol.io/)
|
||
2. Transport: **Streamable HTTP**
|
||
3. URL: `http://localhost:8000/mcp`
|
||
|
||
### 2. Manual SSE Health Check
|
||
You can verify if the server is responding to SSE requests using `curl`:
|
||
```bash
|
||
curl -v -X POST http://localhost:8000/mcp
|
||
```
|
||
*(It should return an SSE stream starting with `event: endpoint`)*
|
||
|
||
### 3. Linting & Formatting
|
||
We use `ruff` for code quality:
|
||
```bash
|
||
# Run the check
|
||
uv run ruff check src
|
||
|
||
# Run the formatter
|
||
uv run ruff format src
|
||
```
|
||
|
||
### 4. Build Multi-Arch Images
|
||
To test if the multi-arch Docker build works locally (requires Docker Buildx):
|
||
```bash
|
||
docker buildx build --platform linux/amd64,linux/arm64 -t strava-mcp-server:test .
|
||
```
|
||
|
||
---
|
||
|
||
### 5. Git Hooks
|
||
|
||
Two hooks are provided in `scripts/hooks/` — install them both after cloning:
|
||
|
||
```bash
|
||
cp scripts/hooks/pre-commit .git/hooks/pre-commit && chmod +x .git/hooks/pre-commit
|
||
cp scripts/hooks/pre-push .git/hooks/pre-push && chmod +x .git/hooks/pre-push
|
||
```
|
||
|
||
#### `pre-commit` — Lint & Format check
|
||
Runs on staged `.py` files before every commit.
|
||
- 🔍 `ruff check` — linting
|
||
- 🎨 `ruff format --check` — formatting
|
||
- 🔧 Fix: `uv run ruff check --fix` + `uv run ruff format`
|
||
- ⚡ Bypass: `git commit --no-verify`
|
||
|
||
#### `pre-push` — Unit tests
|
||
Runs the full unit test suite before every push.
|
||
- 🧪 `pytest tests/unit/ -q`
|
||
- ⚡ Bypass: `git push --no-verify`
|
||
|
||
### 6. Unit Tests
|
||
|
||
Fast, offline unit tests for pure functions and MCP helpers (no Strava API required).
|
||
|
||
```bash
|
||
# Run all unit tests
|
||
uv run pytest tests/unit/ -v
|
||
|
||
# Run with coverage (if pytest-cov is installed)
|
||
uv run pytest tests/unit/ --cov=strava_mcp_server
|
||
```
|
||
|
||
**Test coverage:**
|
||
| Module | Tests |
|
||
|--------|-------|
|
||
| `utils.py` — `parse_iso_to_unix` | `None`, empty, invalid, UTC, offset, date-only |
|
||
| `utils.py` — `format_date_iso` | Normalization, `None`, datetime object, invalid |
|
||
| `utils.py` — `format_date_human` | German format, `None`, datetime object, regex pattern |
|
||
| `tools/*` — `_resource()` | Type, mimeType, URI, JSON validity, audience |
|
||
| `tools/*` — `_user_text()` | Type, text value, audience |
|
||
|
||
---
|
||
|
||
## License
|
||
|
||
MIT
|