Metadata-Version: 2.4
Name: strava-mcp-agent
Version: 0.2.0
Summary: MCP server that exposes your Strava athletic data as tools for Claude and other LLMs
Project-URL: Homepage, https://github.com/koushikmaji/strava-mcp
Project-URL: Repository, https://github.com/koushikmaji/strava-mcp
Project-URL: Issues, https://github.com/koushikmaji/strava-mcp/issues
Author: Koushik Maji
License: MIT
License-File: LICENSE
Keywords: claude,cycling,fitness,llm,mcp,running,strava
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# strava-mcp-agent

**Give Claude access to your Strava data.** An MCP server that exposes your runs, rides, swims, and all Strava metrics as tools for AI-powered coaching, analysis, and conversation.

---

## What it does

`strava-mcp-agent` connects your Strava account to any MCP-compatible client (Claude Desktop, Claude Code, etc.) and provides **13 tools** covering every aspect of your athletic data:

| Tool | Description |
|------|-------------|
| `get_athlete` | Your profile — name, weight, FTP, bio |
| `get_athlete_stats` | All-time & recent totals for run/bike/swim |
| `list_activities` | Browse activities with date/type filtering |
| `get_activity` | Full detail for one activity (splits, HR, cadence, weather) |
| `get_activity_zones` | Heart-rate and power zone distribution |
| `get_activity_laps` | Per-lap pace, HR, and distance breakdown |
| `get_activity_streams` | Raw sensor data (GPS, HR, cadence, watts, altitude) |
| `get_starred_segments` | Your starred segments |
| `get_segment_efforts` | Efforts on a specific segment |
| `get_routes` | Routes you've created |
| `get_gear` | Shoe/bike details and mileage |
| `get_clubs` | Clubs you belong to |
| `get_running_summary` | AI-ready coaching summary (weekly mileage, pace trends, best efforts, HR stats) |

## Quick Start

### Step 1: Install

```bash
pip install strava-mcp-agent
```

### Step 2: Create a Strava API app (one time)

Go to [strava.com/settings/api](https://www.strava.com/settings/api) and fill in:

| Field | What to enter |
|-------|---------------|
| **Application Name** | Anything (e.g. `My Claude MCP`) |
| **Category** | Pick any |
| **Club** | Leave blank |
| **Website** | `http://localhost` |
| **Authorization Callback Domain** | `localhost` |

> The callback domain **must** be `localhost` — this is what allows the setup wizard to receive the authorization code on your machine.

Click **Create**. On the next page, copy your **Client ID** (a number like `123456`) and **Client Secret** (a long code like `abc123def456...`).

### Step 3: Run the setup wizard

```bash
strava-mcp-token
```

It will:
1. Ask for your Client ID and Client Secret
2. Open your browser — click **Authorize** on the Strava page
3. Auto-detect your OS (macOS / Linux / Windows)
4. Find the Python that has the package installed
5. Write the Claude Desktop config file for you

### Step 4: Restart Claude Desktop

That's it. Your 13 Strava tools are ready. Just ask Claude about your runs.

### Manual setup (if you prefer)

<details>
<summary>Click to expand</summary>

Add to your Claude Desktop config:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "strava": {
      "command": "strava-mcp",
      "env": {
        "STRAVA_CLIENT_ID": "your_client_id",
        "STRAVA_CLIENT_SECRET": "your_client_secret",
        "STRAVA_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}
```

</details>

## Usage Examples

Once connected, just talk to Claude:

- *"How was my running this month?"*
- *"Compare my last 5 runs — am I getting faster?"*
- *"What's my average heart rate on long runs vs tempo runs?"*
- *"Show me my weekly mileage trend for the past 2 months"*
- *"What gear has the most miles on it?"*

The `get_running_summary` tool is especially powerful for coaching — it computes weekly mileage, pace trends, best 5K/10K efforts, and heart rate stats, all in one call.

## Security

Credentials are loaded from environment variables only — never hardcoded. The server uses Strava's OAuth2 refresh token flow and automatically handles token renewal.

## Requirements

- Python 3.10+
- A Strava account with API access
- MCP-compatible client (Claude Desktop, Claude Code, etc.)

## License

MIT
