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
- Clone this repository:
git clone https://github.com/gcoombe/strava-mcp.git
cd strava-mcp
- Install dependencies:
npm install
- Copy the example environment file:
cp .env.example .env
- Build the project:
npm run build
Strava API Setup
1. Create a Strava Application
- Go to Strava API Settings
- Create a new application
- Fill in the required information:
- Application Name: Your app name
- Category: Choose appropriate category
- Website: Can use
http://localhostfor testing - Authorization Callback Domain: Use
localhostfor local testing, or your domain for production
- Note your Client ID and Client Secret
- Add them to your
.envfile
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:
-
Generate OAuth credentials for your
.env:echo "OAUTH_CLIENT_ID=$(openssl rand -hex 16)" echo "OAUTH_CLIENT_SECRET=$(openssl rand -hex 16)" -
Expose your server via ngrok or deploy publicly:
ngrok http 3000 -
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
- Server URL:
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 filtersget_activity- Get detailed activity informationcreate_activity- Create a new manual activityupdate_activity- Update an existing activitydelete_activity- Delete an activityget_activity_streams- Get activity data streamsget_activity_comments- Get activity commentsget_activity_kudos- Get activity kudos
Athlete
get_athlete- Get authenticated athlete profileget_athlete_stats- Get athlete statisticsget_athlete_zones- Get athlete training zones
Routes
get_routes- List athlete routesget_route- Get route details
Segments
get_starred_segments- List starred segmentsget_segment- Get segment detailsget_segment_leaderboard- Get segment leaderboardexplore_segments- Explore segments in an area
Clubs
get_athlete_clubs- List athlete clubsget_club- Get club detailsget_club_members- Get club membersget_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 projectnpm run dev- Watch mode for developmentnpm run lint- Lint the codebasenpm test- Run testsnpm start- Start MCP server (stdio mode)npm run start:http- Start HTTP servernpm 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 setupto obtain new tokens
"JWT_SECRET required" error (HTTP mode)
- Add
JWT_SECRETto your.envfile - 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 installto ensure all dependencies are installed
License
MIT