DEPLOYMENT_GUIDE.md

Strava MCP Deployment Guide

This repository contains two different server implementations for different use cases:

🎯 Deployment Options

1. 🌐 Hugging Face Spaces (Web Interface)

Use this for: Web-based interface accessible via browser

Entry Point: app.py → strava_mcp/gradio_server.py

Features:

• Web-based Gradio interface with tabs
• Manual OAuth token input
• Step-by-step authentication guide
• Perfect for sharing and demonstrations

How to Deploy:

1. Upload your code to Hugging Face Spaces
2. Set environment variables in Space settings:

   STRAVA_CLIENT_ID=your_client_id
   STRAVA_CLIENT_SECRET=your_client_secret
   

3. Use the web interface to authenticate and get activities

⚠️ MCP SSE Status: Currently not available on Hugging Face Spaces because:

• HF Spaces uses Gradio 5.20.0 (MCP requires 5.32.0+)
• Will be available when HF Spaces updates their Gradio version
• Use Claude Desktop option below for MCP functionality

2. 🖥️ Claude Desktop (MCP Integration)

Use this for: Direct integration with Claude Desktop application

Entry Point: run_mcp_server.py → strava_mcp/main.py → strava_mcp/server.py

Features:

• Native MCP protocol support
• Direct integration with Claude Desktop
• Automatic OAuth flow (when possible)
• Tools available directly in Claude conversations

How to Setup:

1. Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

   {
     "mcpServers": {
       "strava": {
         "command": "python",
         "args": ["/path/to/strava-mcp/run_mcp_server.py"],
         "env": {
           "STRAVA_CLIENT_ID": "your_client_id",
           "STRAVA_CLIENT_SECRET": "your_client_secret",
           "STRAVA_REFRESH_TOKEN": "your_refresh_token"
         }
       }
     }
   }
   

🔧 Key Differences

Feature	Hugging Face Spaces	Claude Desktop
Interface	Web browser + SSE endpoint	Claude Desktop app
Authentication	Manual token input	Environment variables
OAuth Flow	Manual (with helper)	Can be automatic
Access	Public/shareable	Local only
Protocol	HTTP/Gradio + MCP/SSE	MCP/stdio
Use Case	Demos, sharing, LLM integration	Personal use
MCP Endpoint	/gradio_api/mcp/sse	stdio transport

❌ Common Issues Fixed

ASGI Protocol Errors

Problem: Trying to run both Gradio and MCP server simultaneously caused ASGI conflicts.

Solution: Separated the implementations:

• Hugging Face Spaces: Uses only Gradio (removed mcp_server=True)
• Claude Desktop: Uses only MCP server with stdio transport

Scope Permission Errors

Problem: Refresh tokens created without activity:read scope.

Solution:

• Updated OAuth URLs to include correct scopes: read_all,activity:read,activity:read_all,profile:read_all
• Added clear error messages and guidance
• Created OAuth Helper with step-by-step instructions

📁 File Structure

strava-mcp/
├── app.py                          # 🌐 HF Spaces entry point
├── run_mcp_server.py               # 🖥️ Claude Desktop entry point
├── claude_desktop_config_example.json # Configuration example
├── strava_mcp/
│   ├── gradio_server.py            # 🌐 Web interface (Gradio)
│   ├── server.py                   # 🖥️ MCP server implementation
│   ├── main.py                     # 🖥️ MCP server runner
│   ├── api.py                      # Strava API client
│   ├── auth.py                     # OAuth authentication
│   ├── service.py                  # Business logic
│   ├── models.py                   # Data models
│   └── config.py                   # Settings
└── check_token_scopes.py           # 🔧 Diagnostic tool

🚀 Quick Start

For Hugging Face Spaces:

# Deploy to HF Spaces with app.py as entry point
# Set STRAVA_CLIENT_ID and STRAVA_CLIENT_SECRET in Space settings
# Use web interface to authenticate

For Claude Desktop:

# 1. Get your refresh token
python check_token_scopes.py CLIENT_ID CLIENT_SECRET REFRESH_TOKEN

# 2. Add to Claude Desktop config
# 3. Restart Claude Desktop
# 4. Use Strava tools in conversations

🆘 Troubleshooting

"No MCP tools available" or "TypeError: unexpected keyword argument 'mcp_server'"

• Cause: Hugging Face Spaces currently uses Gradio 5.20.0 (MCP requires 5.32.0+)
• Status: MCP SSE functionality is not available on HF Spaces yet
• Workaround: Use the Claude Desktop integration for MCP functionality
• Future: Will work automatically when HF Spaces updates Gradio

"ASGI Protocol Error"

• Cause: Trying to use mcp_server=True in Gradio
• Fix: Use separate deployments (this is now fixed)

"activity:read_permission missing"

• Cause: Refresh token created without correct scopes
• Fix: Get new token using OAuth Helper with correct scopes

"Service not initialized"

• Cause: Missing environment variables
• Fix: Set STRAVA_CLIENT_ID, STRAVA_CLIENT_SECRET, and STRAVA_REFRESH_TOKEN

🎉 Success!

After these fixes:

• ✅ Hugging Face Spaces deployment works without ASGI errors
• ✅ Claude Desktop integration works with proper MCP protocol
• ✅ Clear separation between web interface and MCP server
• ✅ Better error messages and authentication guidance
• ✅ Comprehensive documentation and examples