FirstCycling MCP Server

MIT License
Overview InspectNew Schema Related Servers Reviews Score
firstcycling-mcp
# FirstCycling MCP Server

This is a Model Context Protocol (MCP) server that provides professional cycling data from FirstCycling. It allows you to retrieve comprehensive information about professional cyclists, race results, race details, and historical cycling data.

## Features

This MCP server offers rich access to professional cycling data, providing tools for:

- Finding information about professional cyclists
- Retrieving race results and details
- Exploring historical race data
- Analyzing rider performance and career progression
- Accessing information about cycling teams and competitions

## Real-World Use Cases

With this MCP server, you can use Claude to:

### Rider Analysis

- **Performance Tracking**: "How has Tadej Pogačar performed in the Tour de France over the years?"
- **Career Progression**: "Show me the team history and career progression of Wout van Aert."
- **Specialization Analysis**: "What are Mathieu van der Poel's results in Monument classics?"
- **Victory Analysis**: "List all WorldTour victories for Jonas Vingegaard."
- **Historical Comparison**: "Compare the Grand Tour results of Primož Roglič and Jonas Vingegaard."

### Race Research

- **Recent Results**: "Show me the results of the 2023 Paris-Roubaix."
- **Historical Context**: "Who are the youngest and oldest winners of the Tour of Flanders?"
- **Team Analysis**: "Get the startlist for the 2023 Tour de France with detailed team information."
- **Race Statistics**: "Show me the victory table for Liège-Bastogne-Liège. Who has won it the most times?"
- **Stage Information**: "Can you show me the stage profiles for the 2023 Giro d'Italia?"

### Sports Journalism

- "Create a detailed profile of Remco Evenepoel for a cycling magazine article."
- "Write a preview for the upcoming Tour de France based on the recent results of top contenders like Tadej Pogačar and Jonas Vingegaard."
- "Analyze the evolution of Tom Pidcock's career based on his race results and team history."

### Cycling Education

- "Explain what makes the Monument classics special using data about their history and winners."
- "Create an educational summary about Grand Tours and their significance in professional cycling."
- "Describe the typical career progression of a professional cyclist using examples from the data."

## Requirements

- Python 3.10 or higher
- `uv` package manager (recommended)
- Dependencies as listed in `pyproject.toml`, including:
  - mcp
  - beautifulsoup4
  - lxml
  - pandas
  - slumber
  - and other packages for web scraping and data processing

## Setup

1. Clone this repository
2. Create and activate a virtual environment:
   ```
   uv venv
   source .venv/bin/activate  # On macOS/Linux
   # or
   .venv\Scripts\activate  # On Windows
   ```
3. Install dependencies:
   ```
   uv pip install -e .
   ```

## FirstCycling API

This server uses the [FirstCycling API](https://github.com/baronet2/FirstCyclingAPI), which has been integrated directly into the project. The API provides methods to fetch data from the FirstCycling website through web scraping.

## MCP Tools

The server exposes the following tools through the Model Context Protocol:

### Rider Information

| Tool | Description |
|------|-------------|
| `get_rider_info` | Get basic biographical information about a rider including nationality, birthdate, weight, height, and current team |
| `get_rider_best_results` | Retrieve a rider's best career results, sorted by importance |
| `get_rider_grand_tour_results` | Get a rider's results in Grand Tours (Tour de France, Giro d'Italia, Vuelta a España) |
| `get_rider_monument_results` | Retrieve a rider's results in cycling's Monument classics |
| `get_rider_team_and_ranking` | Get a rider's team history and UCI ranking evolution over time |
| `get_rider_race_history` | Retrieve a rider's complete race participation history, optionally filtered by year |
| `get_rider_one_day_races` | Get a rider's results in one-day races, optionally filtered by year |
| `get_rider_stage_races` | Get a rider's results in multi-day stage races, optionally filtered by year |
| `get_rider_teams` | Retrieve the complete team history of a rider throughout their career |
| `get_rider_victories` | Get a list of a rider's career victories, with optional filters for WorldTour or UCI races |

### Race Information

| Tool | Description |
|------|-------------|
| `get_race_results` | Retrieve results for a specific race edition by race ID and year |
| `get_race_overview` | Get general information about a race including history, records, and past winners |
| `get_race_stage_profiles` | Retrieve stage profiles and details for multi-stage races |
| `get_race_startlist` | Get the startlist for a specific race edition with detailed or basic team information |
| `get_race_victory_table` | Retrieve the all-time victory table for a race showing riders with most wins |
| `get_race_year_by_year` | Get year-by-year results for a race with optional classification filter |
| `get_race_youngest_oldest_winners` | Retrieve information about the youngest and oldest winners of a race |
| `get_race_stage_victories` | Get information about stage victories in multi-stage races |

### Search Tools

| Tool | Description |
|------|-------------|
| `search_rider` | Search for riders by name, returning their IDs and basic information |
| `search_race` | Search for races by name, returning their IDs and basic information |

## Usage

### Development Mode

You can test the server with MCP Inspector by running:

```
uv run mcp dev firstcycling.py
```

This will start the server and open the MCP Inspector in your browser, allowing you to test the available tools.

### Integration with Claude for Desktop

To integrate this server with Claude for Desktop:

1. Edit the Claude for Desktop config file, located at:
   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`

2. Add the server to your configuration:
   ```json
   {
     "mcpServers": {
       "firstcycling": {
         "command": "uv",
         "args": ["--directory", "/path/to/server/directory", "run", "firstcycling.py"]
       }
     }
   }
   ```

3. Restart Claude for Desktop

## License

MIT
ID: lbkjwm0se5