peloton-mcp

# Peloton MCP Server A local MCP server for **Claude Desktop** that connects to the Peloton API so you can: - Search classes by type, instructor, duration, and difficulty - Get personalized workout suggestions based on your history and goals - View and manage your class Stack (add / remove classes) - Browse instructors and review your recent workouts --- ## Requirements - macOS (Claude Desktop required) - Python 3.10+ - A Peloton account --- ## Quick Setup (5 minutes) ### 1. Clone and install dependencies ```bash git clone https://github.com/yourname/peloton-mcp # or wherever you put it cd peloton-mcp python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt ``` ### 2. Run the setup script The script adds the server to Claude Desktop's config automatically: ```bash ./setup_claude.sh ``` It will prompt for your Peloton username and password, then write the config. Alternatively, pass credentials as environment variables: ```bash PELOTON_USERNAME=you@email.com PELOTON_PASSWORD=yourpassword ./setup_claude.sh ``` ### 3. Restart Claude Desktop Quit and reopen Claude Desktop. You should see a hammer icon (🔨) in the message input area indicating MCP tools are available. --- ## Manual Configuration If you prefer to configure manually, add the following to `~/Library/Application Support/Claude/claude_desktop_config.json`: ```json { "mcpServers": { "peloton": { "command": "/absolute/path/to/peloton-mcp/.venv/bin/python3", "args": ["/absolute/path/to/peloton-mcp/server.py"], "env": { "PELOTON_USERNAME": "your@email.com", "PELOTON_PASSWORD": "yourpassword" } } } } ``` **Replace** `/absolute/path/to/peloton-mcp` with the actual project path. Find it by running `pwd` inside the project directory. Using the virtualenv's Python (`.venv/bin/python3`) ensures the server always has its dependencies available regardless of your system Python state. If you have other MCP servers already configured, add `"peloton": {...}` alongside them inside the existing `"mcpServers"` object — do not duplicate the key. --- ## Usage Once connected, Claude can use all 8 Peloton tools. Try prompts like: | Goal | Example prompt | |---|---| | Find classes | "Search for 45-minute cycling classes" | | Filter by instructor | "Show me strength classes with Robin Arzón" | | Get suggestions | "Suggest classes to help me build cycling endurance this week" | | View your Stack | "What's in my Peloton Stack?" | | Add to Stack | "Add the top-rated 30-minute yoga class to my Stack" | | Review history | "What Peloton classes have I done recently?" | --- ## Available Tools | Tool | What it does | |---|---| | `search_classes` | Search/filter available classes by type, instructor, duration, difficulty | | `get_class_details` | Full details for a specific class (description, equipment, instructor bio) | | `list_instructors` | All Peloton instructors with fitness disciplines | | `get_my_workouts` | Your recent workout history with output stats | | `get_my_stack` | View your current class Stack | | `add_to_stack` | Add one or more classes to your Stack | | `remove_from_stack` | Remove classes from your Stack | | `suggest_classes` | AI-powered workout suggestions based on your history and a stated goal | --- ## Session Management After a successful login, your session token is cached at `~/.peloton_session.json`. The server reuses this on subsequent runs — you won't need to re-authenticate each time. To force a fresh login (e.g. after a password change): ```bash rm ~/.peloton_session.json ``` --- ## Stack API Note Peloton's Stack feature uses **undocumented endpoints**. The server uses community-discovered paths that work as of early 2025. If `get_my_stack`, `add_to_stack`, or `remove_from_stack` return a 404 error, the endpoints may have changed. To find the current paths: 1. Open [members.onepeloton.com](https://members.onepeloton.com) in Chrome/Safari 2. Open DevTools → Network tab 3. Add a class to your Stack on the website 4. Look for the API request URL and update `peloton_client.py` accordingly --- ## Running Tests ```bash python3 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt pytest pytest tests/ -v ``` All tests are fully mocked — no Peloton account or network access needed. --- ## Troubleshooting **Claude Desktop doesn't show the hammer icon** - Verify the path in `claude_desktop_config.json` is absolute and correct - Confirm Python is installed at the path you specified: `which python3` - Check Claude Desktop logs: `~/Library/Logs/Claude/` - Make sure you fully quit and reopened Claude Desktop (Cmd+Q, not just closing the window) **"PELOTON_USERNAME and PELOTON_PASSWORD environment variables must be set"** - The `env` block in `claude_desktop_config.json` is missing or has the wrong key names - Re-run `./setup_claude.sh` to regenerate the config **"Invalid Peloton username or password"** - Verify your credentials work at [members.onepeloton.com](https://members.onepeloton.com) - Delete `~/.peloton_session.json` and try again **Stack tools return 404** - See the Stack API Note section above **Tools time out** - Peloton's API occasionally has slow responses; the default timeout is 15 seconds - Retry the request; if persistent, check [status.onepeloton.com](https://status.onepeloton.com)