gabeperez/strava-mcp

🌴 Strava MCP OAuth - Cloudflare Workers

Production-ready MCP server for Strava with OAuth authentication and real-time webhook notifications

⚠️ IMPORTANT: Personal Use Only - This project is currently designed for single-user/personal deployments. The webhook notification system sends all activity updates to a single Poke API key (yours). Multi-user support with per-user notifications is planned for future releases.

A complete Model Context Protocol (MCP) server for Strava that enables AI assistants (Poke, Claude Desktop, etc.) to access your Strava data through natural language. Plus optional real-time webhook notifications when you complete workouts!

✨ Features

• 🔐 Zero-Config OAuth - Device-based authentication, no URL management
• 🏃 9 MCP Tools - Activities, segments, routes, athlete stats, and more
• 🔔 Real-time Webhooks - Push notifications via Poke for new activities
• 🔄 Auto Token Refresh - Never worry about expired tokens
• 🎨 Beautiful Dashboard - Web UI to view your Strava data
• ⚡ Edge Performance - Global Cloudflare network, <50ms response times
• 💰 Free Tier - 100k requests/day at zero cost

🚀 Quick Start

Note: Deploying to Cloudflare requires some terminal commands, but we've made it as simple as possible!

# Download the project
git clone https://github.com/gabeperez/strava-mcp-oauth.git

# Go into the folder
cd strava-mcp-oauth

# Install dependencies (takes ~30 seconds)
npm install

# Login to Cloudflare (opens browser - just click "Allow")
wrangler login

# Run automated setup (asks you a few questions, then does everything!)
node scripts/setup.js

# 1. Download and install
git clone https://github.com/gabeperez/strava-mcp-oauth.git
cd strava-mcp-oauth
npm install

# 2. Login to Cloudflare (opens browser)
wrangler login

# 3. Create database (KV namespace)
wrangler kv:namespace create STRAVA_SESSIONS
# Copy the "id" from output and paste into wrangler.jsonc

# 4. Set your Strava API credentials
wrangler secret put STRAVA_CLIENT_ID
# Paste your Client ID when prompted

wrangler secret put STRAVA_CLIENT_SECRET
# Paste your Client Secret when prompted

# 5. Deploy to Cloudflare
npm run deploy

# 6. Visit your worker URL to authenticate
open https://your-worker-name.your-subdomain.workers.dev/auth

wrangler secret put STRAVA_WEBHOOK_VERIFY_TOKEN
wrangler secret put POKE_API_KEY

🔔 Real-time Webhooks (Optional)

⚠️ Personal Use Only: Webhooks currently send notifications to a single Poke API key. Only enable if you're the sole user of this deployment. Multi-user webhook support coming soon.

Get instant push notifications via Poke when you finish workouts!

🏃 New Strava Workout!

**Morning Run**
Type: Run
Date: Oct 29, 2025 7:30 AM
Distance: 10.5 km
Duration: 52 minutes
Pace: 4:57 min/km
Elevation: 120m
Avg HR: 145 bpm
🏆 2 PRs!

Quick Webhook Setup

# 1. Set Poke API key (get from https://poke.com/settings/advanced)
wrangler secret put POKE_API_KEY

# 2. Set webhook verification token
wrangler secret put STRAVA_WEBHOOK_VERIFY_TOKEN
# Enter: STRAVA_MCP_WEBHOOK

# 3. Test endpoint
node scripts/manage-webhook.js test

# 4. Create subscription
STRAVA_CLIENT_ID=xxx STRAVA_CLIENT_SECRET=xxx \
node scripts/manage-webhook.js create

# 5. Monitor events
wrangler tail

See for complete instructions

📚 Available MCP Tools

Ask your AI assistant natural language questions, and these tools will be called automatically:

🌐 Endpoints

🎯 Usage Examples

With Poke

1. Add MCP server in Poke settings
2. Use URL: https://your-worker-url.workers.dev/mcp
3. Ask: "What was my pace on yesterday's run?"

With Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "strava": {
      "url": "https://your-worker-url.workers.dev/mcp"
    }
  }
}

Natural Language Queries

• "Show me my recent Strava activities"
• "What was my heart rate during my last run?"
• "Get power data from yesterday's bike ride"
• "Find challenging segments near Boulder"
• "What are my all-time cycling stats?"

🔒 Security Features

• Device Fingerprinting - Automatic authentication by browser
• Token Refresh - Seamless renewal before expiration
• Per-user Isolation - Complete data separation
• Secure Storage - KV encryption for tokens
• CSRF Protection - State validation in OAuth flow
• Rate Limiting - Respects Strava API quotas

🏗️ Architecture

┌─────────────────┐    ┌──────────────────────┐    ┌─────────────────┐
│  AI Assistant   │───▶│  Cloudflare Worker   │───▶│   Strava API    │
│  (Poke/Claude)  │    │                      │    │                 │
│                 │    │ • MCP Server         │    │ • Activities    │
│ Natural Language│    │ • OAuth Handler      │    │ • Segments      │
│ Queries         │    │ • Device Auth        │    │ • Routes        │
│                 │    │ • Token Manager      │    │ • Stats         │
│                 │    │ • Webhook Handler    │    │                 │
└─────────────────┘    └──────────────────────┘    └─────────────────┘
                                 │                           │
                                 ▼                           ▼
                       ┌──────────────────┐       ┌─────────────────┐
                       │   Cloudflare KV  │       │   Poke API      │
                       │  • Sessions      │       │  • Push Notify  │
                       │  • OAuth Tokens  │       │  • iMessage/SMS │
                       │  • Activity Data │       └─────────────────┘
                       └──────────────────┘

📖 Documentation

• - Step-by-step deployment (5 minutes)
• - Complete webhook guide
• - Quick webhook reference
• - Development & architecture details
• - Template publishing guide

🛠️ Tech Stack

• Runtime: Cloudflare Workers (V8 isolates)
• Framework: Hono (lightweight web framework)
• Storage: Cloudflare KV (sessions & tokens)
• Protocol: Model Context Protocol (MCP)
• Auth: Strava OAuth 2.0
• Notifications: Poke API (optional)

💰 Pricing

100% Free! Runs on Cloudflare's generous free tier:

• Workers: 100,000 requests/day
• KV Storage: 100,000 reads/day, 1,000 writes/day
• Bandwidth: Unlimited on free tier

Perfect for personal use. No credit card required.

🔧 Development

Local Testing

# Install dependencies
npm install

# Start local server
wrangler dev

# Visit http://localhost:8787

Run Tests

npm test

Environment Variables

See for all configuration options.

🐛 Troubleshooting

🗺️ Roadmap

Coming Soon

• Multi-user Webhook Support - Per-user Poke API keys and notification routing
• Public stravamcp.com Service - Hosted version for non-technical users
• More Notification Channels - Discord, Slack, email, etc.
• Activity Analytics - Trends, insights, and training load tracking
• Custom Webhook Filters - Choose which activities trigger notifications
• Web Dashboard Enhancements - More stats, charts, and visualizations

Interested in contributing to any of these? Open a discussion!

🤝 Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

MIT License - see file for details.

🙏 Credits

• Built with Hono
• Powered by Cloudflare Workers
• MCP by Anthropic
• Notifications via Poke
• Inspired by the Strava community 🏃‍♀️🚴‍♂️

⭐ Star History

If this project helped you, consider giving it a star!

Made with ❤️ for athletes who love data

Report Bug · Request Feature · Discussions