Strava MCP Server

A Model Context Protocol (MCP) server for integrating with the Strava API. This server provides comprehensive access to all major Strava API endpoints including activities, athlete data, routes, segments, clubs, and gear.

Transport Modes

This server supports two transport modes per the MCP specification:

Mode	Command	Auth	Use Case
stdio	npm start	Environment tokens	Claude Desktop (single user)
HTTP	npm run start:http	OAuth + JWT	ChatGPT, REST clients (multi-user)

Features

Activity Management

• Get athlete activities with filters (date range, pagination)
• Get detailed activity information
• Create, update, and delete activities
• Access activity streams (GPS, heart rate, power, cadence, etc.)
• Get activity comments and kudos

Athlete Data

• Get authenticated athlete profile
• Get athlete statistics and totals
• Get athlete zones (heart rate and power)

Routes

• Get athlete routes
• Get detailed route information

Segments

• Get starred segments
• Get segment details
• Get segment leaderboards with filters
• Explore segments in geographic areas

Clubs & Social

• Get athlete clubs
• Get club details and members
• Get club activities

Gear

• Get detailed gear information

Prerequisites

• Node.js 18+ (LTS recommended)
• A Strava account
• Strava API credentials (Client ID and Client Secret)

Installation

1. Clone this repository:

git clone https://github.com/gcoombe/strava-mcp.git
cd strava-mcp

2. Install dependencies:

npm install

3. Copy the example environment file:

cp .env.example .env

4. Build the project:

npm run build

Strava API Setup

1. Create a Strava Application

1. Go to Strava API Settings
2. Create a new application
3. Fill in the required information:
   • Application Name: Your app name
   • Category: Choose appropriate category
   • Website: Can use http://localhost for testing
   • Authorization Callback Domain: Use localhost for local testing, or your domain for production
4. Note your Client ID and Client Secret
5. Add them to your .env file

2. Choose Your Transport Mode

stdio Mode (Claude Desktop)

For single-user use with Claude Desktop:

# Run the interactive setup to get your personal tokens
npm run setup

# Start the server
npm start

The setup script will guide you through the OAuth flow and save tokens to .env.

HTTP Mode (Multi-user)

For multi-user deployments (ChatGPT, REST clients):

# Add HTTP-specific variables to .env:
# OAUTH_CLIENT_ID=<generate with: openssl rand -hex 16>
# OAUTH_CLIENT_SECRET=<generate with: openssl rand -hex 16>
# JWT_SECRET=<generate with: openssl rand -base64 32>
# STRAVA_REDIRECT_URI=http://localhost:3000/auth/strava/callback

# Start the HTTP server
npm run start:http

Users authenticate via OAuth at /auth/authorize and receive a JWT for API access.

ChatGPT Configuration

To use with ChatGPT:

1. Generate OAuth credentials for your .env:

   echo "OAUTH_CLIENT_ID=$(openssl rand -hex 16)"
   echo "OAUTH_CLIENT_SECRET=$(openssl rand -hex 16)"
   

2. Expose your server via ngrok or deploy publicly:

   ngrok http 3000
   

3. In ChatGPT, configure your MCP server with:

   • Server URL: https://your-ngrok-url.ngrok-free.dev
   • OAuth Client ID: Value from your .env
   • OAuth Client Secret: Value from your .env

ChatGPT will automatically discover the OAuth endpoints via /.well-known/oauth-authorization-server.

MCP Configuration (stdio Mode)

Claude Desktop

Add this to your Claude Desktop configuration 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/strava-mcp/dist/index.js"
      ]
    }
  }
}

HTTP API Reference

When running in HTTP mode (npm run start:http), the following endpoints are available:

OAuth 2.0 Endpoints

Endpoint	Method	Description
/.well-known/oauth-authorization-server	GET	OAuth server metadata (RFC 8414)
/auth/authorize	GET	OAuth authorization endpoint (redirects to Strava)
/auth/callback	GET	Internal OAuth callback from Strava
/auth/token	POST	Exchange authorization code for JWT
/auth/me	GET	Get current athlete info (requires JWT)
/auth/logout	POST	Revoke tokens (requires JWT)

Tools

Endpoint	Method	Auth	Description
/tools	GET	-	List all available tools
/tools/:name	GET	-	Get tool schema
/tools/:name	POST	JWT	Execute a tool

Example Usage

# Start the server
npm run start:http

# For ChatGPT: Configure with your server URL and OAuth credentials
# ChatGPT will handle the OAuth flow automatically

# For manual testing with curl:
# 1. List tools (no auth required)
curl http://localhost:3000/tools

# 2. After completing OAuth flow, use the JWT for API calls
TOKEN="your-jwt-token"

# Get athlete profile
curl -X POST http://localhost:3000/tools/get_athlete \
  -H "Authorization: Bearer $TOKEN"

# Get recent activities
curl -X POST http://localhost:3000/tools/get_activities \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"per_page": 10}'

Available Tools

Activities

• get_activities - List athlete activities with filters
• get_activity - Get detailed activity information
• create_activity - Create a new manual activity
• update_activity - Update an existing activity
• delete_activity - Delete an activity
• get_activity_streams - Get activity data streams
• get_activity_comments - Get activity comments
• get_activity_kudos - Get activity kudos

Athlete

• get_athlete - Get authenticated athlete profile
• get_athlete_stats - Get athlete statistics
• get_athlete_zones - Get athlete training zones

Routes

• get_routes - List athlete routes
• get_route - Get route details

Segments

• get_starred_segments - List starred segments
• get_segment - Get segment details
• get_segment_leaderboard - Get segment leaderboard
• explore_segments - Explore segments in an area

Clubs

• get_athlete_clubs - List athlete clubs
• get_club - Get club details
• get_club_members - Get club members
• get_club_activities - Get club activities

Gear

• get_gear - Get gear details

Environment Variables

Variable	Required	Mode	Description
STRAVA_CLIENT_ID	Yes	Both	Strava API client ID
STRAVA_CLIENT_SECRET	Yes	Both	Strava API client secret
STRAVA_ACCESS_TOKEN	Yes	stdio	User's access token
STRAVA_REFRESH_TOKEN	Yes	stdio	User's refresh token
STRAVA_EXPIRES_AT	Yes	stdio	Token expiration timestamp
OAUTH_CLIENT_ID	Yes	HTTP	OAuth client ID for ChatGPT (you create this)
OAUTH_CLIENT_SECRET	Yes	HTTP	OAuth client secret for ChatGPT (you create this)
JWT_SECRET	Yes	HTTP	Secret for signing JWTs
JWT_EXPIRES_IN	No	HTTP	JWT expiration (default: 7d)
STRAVA_REDIRECT_URI	Yes	HTTP	OAuth callback URL
DATABASE_PATH	No	HTTP	SQLite path (default: ./data/strava-mcp.db)
HTTP_PORT	No	HTTP	Server port (default: 3000)

Development

Scripts

• npm run build - Build the TypeScript project
• npm run dev - Watch mode for development
• npm run lint - Lint the codebase
• npm test - Run tests
• npm start - Start MCP server (stdio mode)
• npm run start:http - Start HTTP server
• npm run setup - Interactive OAuth setup

Project Structure

strava-mcp/
├── src/
│   ├── index.ts              # Entry point (mode selection)
│   ├── auth.ts               # Strava OAuth handling
│   ├── strava-client.ts      # Strava API client
│   ├── http-server.ts        # Express HTTP server
│   ├── create-tools.ts       # Tool initialization
│   ├── db.ts                 # SQLite database (HTTP mode)
│   ├── auth/                 # HTTP auth module
│   │   ├── jwt.ts            # JWT utilities
│   │   ├── middleware.ts     # Auth middleware
│   │   └── routes.ts         # OAuth endpoints
│   ├── types/
│   │   └── strava.ts         # TypeScript definitions
│   ├── tools/                # MCP tool implementations
│   │   ├── activities.ts
│   │   ├── athlete.ts
│   │   ├── routes.ts
│   │   ├── segments.ts
│   │   ├── clubs.ts
│   │   └── gear.ts
│   └── utils/
│       └── data-reducer.ts   # Response optimization
├── data/                     # SQLite database (HTTP mode)
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

Token Refresh

The server automatically refreshes access tokens when they expire:

• stdio mode: Tokens are refreshed in memory
• HTTP mode: Refreshed tokens are persisted to SQLite

Rate Limiting

Strava has rate limits:

• 100 requests per 15 minutes
• 1,000 requests per day

The server does not currently implement rate limiting, so use responsibly.

Troubleshooting

"No tokens available" error (stdio mode)

• Ensure all STRAVA_* environment variables are set in .env
• Run npm run setup to obtain new tokens

"JWT_SECRET required" error (HTTP mode)

• Add JWT_SECRET to your .env file
• Generate one with: openssl rand -base64 32

"No tokens found for user" error (HTTP mode)

• User needs to re-authenticate at /auth/strava
• Tokens may have been revoked by Strava

"Failed to refresh token" error

• Your refresh token may have been revoked
• Go through the OAuth flow again to get new tokens

Build errors

• Ensure you're using Node.js 18+ LTS
• Run npm install to ensure all dependencies are installed

License

MIT

Resources

• Strava API Documentation
• Model Context Protocol
• MCP Authorization Spec
• Strava API Settings