🚴 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 and the MCP 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
• Installation & Deployment
  • Docker (Recommended)
  • Local Python (uv)
• Strava API Setup
• Connecting with MCP Clients
• MCP Primitives
• Project Structure
• Design Decisions
• CI/CD (Gitea Actions)
• Development & Testing
  • Git Hooks
• Known Strava API Limitations
• Troubleshooting

Requirements

• A Strava account with API access
• A Strava API Application
• Docker (for containerized deployment) OR Python 3.10+ & uv

Installation & Deployment

Docker (Recommended for self-hosting)

A pre-built multi-arch image (amd64/arm64) is automatically published to the Gitea registry on every release.

1. Authenticate first (only needed once, saves credentials to ~/.config/strava-mcp-server/config.env):

uvx --from strava-mcp-server-hnrx auth

2. Pull and run the image:

# Pull the latest release
docker pull git.hnrx.net/hnrx/strava-mcp-server:latest

# Run with your credentials from the config file
docker run --rm -p 8000:8000 \
  -e STRAVA_CLIENT_ID=<your_client_id> \
  -e STRAVA_CLIENT_SECRET=<your_client_secret> \
  -e STRAVA_REFRESH_TOKEN=<your_refresh_token> \
  -e MCP_TRANSPORT=http \
  git.hnrx.net/hnrx/strava-mcp-server:latest

Or using your config file directly:

docker run --rm -p 8000:8000 \
  --env-file ~/.config/strava-mcp-server/config.env \
  -e MCP_TRANSPORT=http \
  git.hnrx.net/hnrx/strava-mcp-server:latest

Tip: Pin to a specific version for stability, e.g. git.hnrx.net/hnrx/strava-mcp-server:v0.2.0

git clone https://git.hnrx.net/hnrx/strava-mcp-server.git
cd strava-mcp-server
docker build -t strava-mcp-server:latest .
docker run --rm -p 8000:8000 --env-file ~/.config/strava-mcp-server/config.env -e MCP_TRANSPORT=http 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:

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

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:

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
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:

cp .env.example .env

Edit .env and fill in your Client ID and Secret:

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:

{
  "mcpServers": {
    "strava": {
      "url": "http://localhost:8000/mcp",
      "transport": "streamable-http"
    }
  }
}

MCP Primitives

Tools

Design Decisions

For a detailed list of architectural choices, unit standardizations, and LLM-specific optimizations, please refer to: 👉 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 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):

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/
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:

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:

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

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:

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

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

License

MIT