claudex-strava-mcp

A Model Context Protocol (MCP) server that connects Claude to your Strava fitness data. Ask Claude questions about your real training history in plain English — no dashboards, no manual exports.

Built with TypeScript, the MCP SDK, and Zod schema validation. Automatic OAuth token refresh included.

What you can ask Claude

• "How many walks did I do this month?"
• "Where were my last 3 activities?"
• "How do my 2025 and 2026 activity counts compare?"
• "Which of my activities had the most stop time?"
• "Am I hitting my Zone 2 training targets?"

Prerequisites

• Node.js 18+
• A Strava account with activities
• A Strava API app (create one here)
• Claude Desktop (or any MCP-compatible client)

Setup

1. Clone and install

git clone https://github.com/your-username/claudex-strava-mcp
cd claudex-strava-mcp
npm install

2. Create your Strava API app

Go to strava.com/settings/api and create an app. Set the Authorization Callback Domain to localhost.

You'll receive a Client ID and Client Secret — keep these safe.

3. Get your refresh token

Copy the example env file and fill in your Client ID and Secret:

cp .env.example .env
# Edit .env and add your STRAVA_CLIENT_ID and STRAVA_CLIENT_SECRET

Then run the OAuth helper:

npx tsx scripts/get-token.ts

This will:

1. Print an authorization URL — open it in your browser
2. Ask you to authorize the app on Strava
3. Redirect to localhost and exchange the code for tokens
4. Print your STRAVA_REFRESH_TOKEN in the terminal

Copy the printed refresh token into your .env:

STRAVA_CLIENT_ID=your_client_id
STRAVA_CLIENT_SECRET=your_client_secret
STRAVA_REFRESH_TOKEN=your_refresh_token

4. Build the server

npm run build

This compiles TypeScript to dist/.

5. Configure Claude Desktop

Add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "strava": {
      "command": "node",
      "args": ["/absolute/path/to/claudex-strava-mcp/dist/index.js"],
      "env": {
        "STRAVA_CLIENT_ID": "your_client_id",
        "STRAVA_CLIENT_SECRET": "your_client_secret",
        "STRAVA_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

Restart Claude Desktop. The Strava tools will appear in Claude's tool list.

Project structure

claudex-strava-mcp/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── strava-client.ts   # Strava API client with auto token refresh
│   └── tools.ts           # 8 MCP tool definitions (Zod-validated)
├── scripts/
│   └── get-token.ts       # One-time OAuth token helper
├── .env.example           # Template — copy to .env and fill in values
├── .gitignore
├── package.json
└── tsconfig.json

Available tools

How it works

The server uses the MCP SDK's McpServer class and registers tools using Zod schemas for runtime validation. The Strava client handles OAuth token refresh automatically — if your access token is within 60 seconds of expiring, it refreshes using your stored refresh token before making any API call.

Claude prompt
    │
    ▼
MCP Tool Layer (TypeScript)
    │
    ├── list_activities  ──► GET /athlete/activities
    ├── get_activity     ──► GET /activities/{id}
    ├── get_activity_zones ► GET /activities/{id}/zones
    └── ...
    │
    ▼
Strava API
    │
    ▼
Structured JSON → Claude reasons → Natural language response

Development

npm run dev   # Watch mode — recompiles on save
npm run build # Production build
npm start     # Run compiled server

Security notes

• Never commit your .env file — it's in .gitignore
• Rotate your Strava client secret at strava.com/settings/api if it's ever exposed
• The OAuth scopes requested are read, activity:read_all, and profile:read_all — read-only access only

License

MIT

Built by [Mostafa Didar Mahdi](https://linkedin.com/in/mostafadidar) — Data Scientist, Anthropic-certified AI practitioner, Adelaide.