# Strava MCP Server

An open-source Model Context Protocol (MCP) server that connects AI agents to your Strava data.

## Features
- **Headless Adapter**: No UI, just pure MCP tools and resources.
- **Privacy First**: Tokens stored locally (`~/.config/strava-mcp/`), never sent to 3rd parties.
- **Resilient**: Built-in rate limiting (handles 429s) and SQLite caching.
- **Educational**: Clean, readable Python 3.11+ code with type hints.

## Prerequisites
- Python 3.11 or higher
- Strava Account (for API credentials)

## Quick Start (Dry Run)
You can test the server immediately without Strava credentials using the mock data mode.

```bash
# Install dependencies
python3 -m pip install -e .

# Run the smoke test (verifies MCP protocol via stdio)
python3 scripts/smoke_test.py
```

## Setup (Real Data)

### 1. Get Strava Credentials
1. Go to [Strava API Settings](https://www.strava.com/settings/api).
2. Create an application.
   - **Callback Domain**: `localhost`

### 2. Authorization
Run the local helper script to perform the OAuth handshake. This will open your browser.

```bash
export STRAVA_CLIENT_ID=your_client_id
export STRAVA_CLIENT_SECRET=your_client_secret
python3 scripts/strava_auth.py
```
*Tokens are saved to `~/.config/strava-mcp/credentials.json`.*

### 3. Usage with Claude Code
Configure `claude` to use this server.

**File: `~/.config/claude/config.json`** (or equivalent MCP manager config)
```json
{
  "mcpServers": {
    "strava": {
      "command": "python3",
      "args": ["-m", "strava_mcp.server"],
      "env": {
        "PYTHONPATH": "/path/to/strava-mcp/src" 
      }
    }
  }
}
```

Or run directly if installed in your environment:
```json
{
  "mcpServers": {
    "strava": {
      "command": "uv",
      "args": ["run", "python", "-m", "strava_mcp.server"]
    }
  }
}
```

## Tools Available

| Tool | Description |
|------|-------------|
| `get_athlete_profile` | Returns your profile stats. |
| `list_activities` | Fetch recent activities (supports date filtering). |
| `get_activity` | Detailed view of a single activity. |
| `weekly_summary` | Aggregated stats (distance, elevation) for a given week. |

## Resources
- `strava://athlete/profile`: Direct read of profile.
- `strava://activities/recent`: Most recent 10 activities.

## Architecture
- **Tech Stack**: Python, FastMCP, Httpx, SQLite, Pydantic.
- **Caching**: GET requests are cached in SQLite with a TTL (default 5 mins for lists).
- **Rate Limiting**: Respects `X-RateLimit-*` headers to prevent API bans.