Ridewithgps MCP

🚀 RideWithGPS MCP Server

The AI-powered companion for cyclists to manage their cycling adventures, providing access to the RideWithGPS API.

🚀 Quick Start

The RideWithGPS MCP Server is a Model Context Protocol (MCP) server that offers access to the RideWithGPS API. It enables you to interact with routes, trips, events, and user data.

✨ Features

• Route Retrival: Retrieve a list of routes and detailed information about specific routes.
• Trip & Activity Data: Get a list of trips/activities and detailed information about specific trips.
• User Profile: Retrieve user profile information.
• Event Participation: Retrieve a list of events and detailed information about specific events.
• Data Synchronization: Retrieve items that the user has interacted with since a given datetime.

📦 Installation

Requirements

• Node.js: 18.0.0 or higher, 20.0.0 or newer recommended (Download here)

Setup Steps

1. Clone the repository and change into its directory:

git clone https://github.com/boezzz/ridewithgps-mcp.git
cd ridewithgps-mcp

2. Build the server app:

npm install
npm run build

3. Configure Claude Desktop:
   • Install the Claude desktop app which supports MCP. Other commonly seen MCP clients should also work.
   • Get your RideWithGPS API credentials:
     • API Key: Visit the developer settings page in your RideWithGPS account and create an API client.
     • Authentication Token: Select the API Client you created and go to its edit page. Click on 'Create new Auth Token' to obtain a new authentication token.
   • Open your Claude Desktop settings, go to Developers, and select 'Edit Config'. Alternatively, in your claude_desktop_config.json file, add a new MCP server:

{
  "mcpServers": {
    "ridewithgps-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/ridewithgps-mcp/build/index.js"],
      "env": {
        "RWGPS_API_KEY": "your_api_key_here",
        "RWGPS_AUTH_TOKEN": "your_auth_token_here"
      }
    }
  }
}

💻 Usage Examples

Example queries

• "Show me my recent routes"
• "Get details for the century route I created yesterday"
• "List my cycling trips from last month"
• "What events do I have coming up that I'll probably chicken out of?"
• "Show me my user profile so I can admire my optimistically low weight setting"
• "Sync my data since last week when I pretended that walk to the coffee shop was a training ride"

📚 Documentation

Tools

This MCP server implements the following tools:

Route Retrival

• get_routes: Retrieve a list of routes owned by the user on RideWithGPS, ordered by updated_at descending.

⚠️ Important Note

This tool can only access routes that you personally own. Routes that are shared with you but belong to other people will not appear in your results.
If you want to use a shared route with this server, please make a copy of it into your own RideWithGPS account first.

• get_route_details: Retrieve full details for a specific route including track points, course points, and points of interest. You can find the available list of information here

Trip & Activity Data

• get_trips: Retrieve a list of trips/activities owned by the user on RideWithGPS, ordered by updated_at descending.
• get_trip_details: Retrieve full details for a specific trip including track points and performance data. You can find the available list of information here

User Profile

• get_current_user: Retrieve profile information for the user.

Event Participation

• get_events: Retrieve a paginated list of events owned by the user, ordered by created_at descending.
• get_event_details: Retrieve full details for a specific event including associated routes.

Data Synchronization

• sync_user_data: Retrieve items (routes and/or trips) that the user has interacted with since a given datetime.

API Coverage

This MCP server implements the main RideWithGPS API endpoints for individual users, excluding organization-specific features. For complete API documentation, see: https://github.com/ridewithgps/developers

🔧 Technical Details

Development

Contributors are welcome! To contribute to this project:

1. Fork this repository to your own GitHub account.
2. Clone your fork locally.
3. Install dependencies: npm install
4. Make your changes to the TypeScript source files in src/
5. Build the project: npm run build
6. Test your changes using npm run inspector
7. Commit and push your changes to your fork.
8. Submit a pull request to the main repository for review.

Development Roadmap

• Utilize OAuth for secure user authentication.
• Deploy the MCP server to Smithery/Glama for distribution.
• Incorporate geospatially-aware track points; currently, only the number is displayed.
• Make pagination optional; it would also be helpful to return trips in descending order by departed time instead of updated time.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.