💻 Development

Everything you need to contribute to the Strava MCP Server.

Prerequisites

Python 3.10+
uv (curl -LsSf https://astral.sh/uv/install.sh | sh)
Docker (optional, for image builds)

Setup

git clone https://git.hnrx.net/hnrx/strava-mcp-server.git
cd strava-mcp-server

# Install all dependencies (including dev tools)
uv sync

# Authenticate with your Strava account
uv run auth

# Start the server in STDIO mode
uv run server

# Start in HTTP mode
MCP_TRANSPORT=http uv run server

Project Structure

strava-mcp-server/
├── src/strava_mcp_server/
│   ├── main.py              # Entry point & FastMCP setup
│   ├── config.py            # Platform config path resolution
│   ├── strava_client.py     # Strava API client with token refresh
│   ├── utils.py             # Date/time helpers
│   ├── get_token.py         # Interactive auth wizard
│   └── tools/
│       ├── __init__.py      # Tool registration
│       ├── athlete.py
│       ├── activities.py
│       ├── clubs.py
│       ├── routes.py
│       ├── segments.py
│       ├── segment_efforts.py
│       ├── gear.py
│       ├── prompts.py
│       └── server_info.py
├── tests/
│   └── unit/                # Unit tests (offline, no API required)
├── docs/
│   └── DESIGN_DECISIONS.md
├── website/                 # Landing page (deployed to S3)
├── .gitea/workflows/        # CI/CD pipelines
├── pyproject.toml
└── Dockerfile

Testing

Unit Tests (offline, no Strava API required)

# Run all unit tests
uv run pytest tests/unit/ -v

# With coverage
uv run pytest tests/unit/ --cov=strava_mcp_server

MCP Inspector (interactive testing)

# STDIO mode — fastest
npx @modelcontextprotocol/inspector uv run server

# HTTP mode — connect to running server at localhost:8000

Manual SSE Health Check

curl -v -X POST http://localhost:8000/mcp

Linting & Formatting

# Check for issues
uv run ruff check src

# Auto-fix issues
uv run ruff check --fix src

# Format code
uv run ruff format src

Git Hooks

Install the pre-configured hooks 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

Hook	Runs	Checks
`pre-commit`	Before every commit	`ruff check` + `ruff format --check` on staged files
`pre-push`	Before every push	Full unit test suite

Bypass with git commit --no-verify or git push --no-verify.

Adding a New Tool

Create or edit a file in src/strava_mcp_server/tools/
Implement a register(mcp, strava) function
Import and call it in tools/__init__.py

Each tool should return a list with two items:

A TextContent with formatted Markdown (for the user)
An EmbeddedResource with JSON (for the LLM)

See existing tools like athlete.py for reference.

Building the Docker Image Locally

docker buildx build --platform linux/amd64,linux/arm64 -t strava-mcp-server:test .

Back to Home