# Sportmonks MCP Server

A Model Context Protocol (MCP) server for the [Sportmonks Football API v3](https://docs.sportmonks.com/v3). Exposes **150+ tools** covering every endpoint — fixtures, leagues, teams, players, odds, predictions, standings, transfers, and more.

## Setup

### 1. Install dependencies

```bash
npm install
```

### 2. Get your API token

Create a free token at [MySportmonks](https://my.sportmonks.com/api/tokens).

### 3. Set environment variable

```bash
export SPORTMONKS_API_TOKEN=your_token_here
```

### 4. Run the server

```bash
node src/index.js
```

---

## Connect to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sportmonks": {
      "command": "node",
      "args": ["/absolute/path/to/sportmonks-mcp/src/index.js"],
      "env": {
        "SPORTMONKS_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

## Connect to Cursor

Edit `.cursor/mcp.json` in your project:

```json
{
  "mcpServers": {
    "sportmonks": {
      "command": "node",
      "args": ["/absolute/path/to/sportmonks-mcp/src/index.js"],
      "env": {
        "SPORTMONKS_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

---

## Available Tools (150+)

### Livescores
| Tool | Description |
|------|-------------|
| `get_inplay_livescores` | All fixtures currently being played |
| `get_all_livescores` | Fixtures 15 min before/after match |
| `get_latest_livescores` | Livescores updated in last 10 seconds |

### Fixtures
| Tool | Description |
|------|-------------|
| `get_all_fixtures` | All fixtures (paginated) |
| `get_fixture_by_id` | Single fixture by ID |
| `get_fixtures_by_multiple_ids` | Up to 50 fixtures by IDs |
| `get_fixtures_by_date` | Fixtures on a date |
| `get_fixtures_by_date_range` | Fixtures in a date range (max 100 days) |
| `get_fixtures_by_date_range_for_team` | A team's fixtures in a date range |
| `get_fixtures_head_to_head` | Head-to-head between two teams |
| `search_fixtures_by_name` | Search by name |
| `get_upcoming_fixtures_by_market_id` | Upcoming fixtures for an odds market |
| `get_upcoming_fixtures_by_tv_station_id` | Upcoming fixtures on a TV station |
| `get_past_fixtures_by_tv_station_id` | Past fixtures on a TV station |
| `get_latest_updated_fixtures` | Fixtures updated in last 10 seconds |

### Leagues
| Tool | Description |
|------|-------------|
| `get_all_leagues` | All leagues (paginated) |
| `get_league_by_id` | Single league by ID |
| `get_leagues_live` | Leagues with live fixtures |
| `get_leagues_by_fixture_date` | Leagues with fixtures on a date |
| `get_leagues_by_country_id` | Leagues in a country |
| `search_leagues_by_name` | Search by name |
| `get_leagues_by_team_id` | All leagues for a team (historical) |
| `get_current_leagues_by_team_id` | Current leagues for a team |

### Seasons
`get_all_seasons` · `get_season_by_id` · `get_seasons_by_team_id` · `search_seasons_by_name` · `get_brackets_by_season_id`

### Stages
`get_all_stages` · `get_stage_by_id` · `get_stages_by_season_id` · `search_stages_by_name`

### Rounds
`get_all_rounds` · `get_round_by_id` · `get_rounds_by_season_id` · `search_rounds_by_name`

### Standings
`get_all_standings` · `get_standings_by_season_id` · `get_standings_by_round_id` · `get_standing_corrections_by_season_id` · `get_live_standings_by_league_id` · `get_grouped_standings_by_round_id`

### Topscorers
`get_topscorers_by_season_id` · `get_topscorers_by_stage_id`

### Statistics
`get_season_statistics_by_participant` · `get_stage_statistics_by_id` · `get_round_statistics_by_id`

### Schedules
`get_schedules_by_season_id` · `get_schedules_by_team_id` · `get_schedules_by_season_and_team`

### Teams
`get_all_teams` · `get_team_by_id` · `get_teams_by_country_id` · `get_teams_by_season_id` · `search_teams_by_name`

### Players
`get_all_players` · `get_player_by_id` · `get_players_by_country_id` · `search_players_by_name` · `get_last_updated_players`

### Team Squads
`get_team_squad` · `get_extended_team_squad` · `get_team_squad_by_season`

### Coaches
`get_all_coaches` · `get_coach_by_id` · `get_coaches_by_country_id` · `search_coaches_by_name` · `get_last_updated_coaches`

### Referees
`get_all_referees` · `get_referee_by_id` · `get_referees_by_country_id` · `get_referees_by_season_id` · `search_referees_by_name`

### Transfers
`get_all_transfers` · `get_transfer_by_id` · `get_latest_transfers` · `get_transfers_by_date_range` · `get_transfers_by_team_id` · `get_transfers_by_player_id`

### Transfer Rumours
`get_all_transfer_rumours` · `get_transfer_rumour_by_id` · `get_transfer_rumours_by_date_range` · `get_transfer_rumours_by_team_id` · `get_transfer_rumours_by_player_id`

### Venues
`get_all_venues` · `get_venue_by_id` · `get_venues_by_season_id` · `search_venues_by_name`

### Odds (Standard Pre-match)
`get_all_prematch_odds` · `get_prematch_odds_by_fixture_id` · `get_prematch_odds_by_fixture_and_bookmaker` · `get_prematch_odds_by_fixture_and_market` · `get_last_updated_prematch_odds`

### Odds (Inplay)
`get_all_inplay_odds` · `get_inplay_odds_by_fixture_id` · `get_inplay_odds_by_fixture_and_bookmaker` · `get_inplay_odds_by_fixture_and_market` · `get_last_updated_inplay_odds`

### Odds (Premium)
`get_all_premium_odds` · `get_premium_odds_by_fixture_id` · `get_premium_odds_by_fixture_and_bookmaker` · `get_premium_odds_by_fixture_and_market` · `get_all_historical_odds`

### Markets
`get_all_markets` · `get_all_premium_markets` · `get_market_by_id` · `search_markets_by_name`

### Bookmakers
`get_all_bookmakers` · `get_all_premium_bookmakers` · `get_bookmaker_by_id` · `search_bookmakers_by_name` · `get_bookmakers_by_fixture_id` · `get_bookmaker_match_id_mappings_by_fixture_id`

### Predictions
`get_probabilities` · `get_predictability_by_league_id` · `get_probabilities_by_fixture_id` · `get_value_bets` · `get_value_bets_by_fixture_id` · `get_live_probabilities` · `get_live_probabilities_by_fixture_id`

### News
`get_prematch_news` · `get_prematch_news_by_season_id` · `get_prematch_news_for_upcoming` · `get_postmatch_news` · `get_postmatch_news_by_season_id`

### Rivals
`get_all_rivals` · `get_rivals_by_team_id`

### Commentaries
`get_all_commentaries` · `get_commentaries_by_fixture_id`

### Expected Goals (xG)
`get_expected_goals_by_team` · `get_expected_goals_by_player` · `get_expected_lineups_by_team` · `get_expected_lineups_by_player`

### Match Facts (beta)
`get_all_match_facts` · `get_match_facts_by_fixture_id` · `get_match_facts_by_date_range` · `get_match_facts_by_league_id`

### Team Rankings (beta)
`get_all_team_rankings` · `get_team_rankings_by_team_id` · `get_team_rankings_by_date`

### Team of the Week (TOTW)
`get_all_totws` · `get_totw_by_round_id` · `get_latest_totw`

### TV Stations
`get_all_tv_stations` · `get_tv_station_by_id` · `get_tv_stations_by_fixture_id`

### States & Types
`get_all_states` · `get_state_by_id` · `get_all_types` · `get_type_by_id` · `get_types_by_entity`

### Core API — Countries & Geography
`get_all_continents` · `get_continent_by_id` · `get_all_countries` · `get_country_by_id` · `search_countries_by_name` · `get_all_regions` · `get_region_by_id` · `search_regions_by_name` · `get_all_cities` · `get_city_by_id` · `search_cities_by_name`

### Core API — Utilities
`get_all_timezones` · `get_all_entity_filters` · `get_all_core_types` · `get_core_type_by_id` · `get_core_types_by_entity`

### My Sportmonks
`get_my_enrichments` · `get_my_resources` · `get_my_leagues` · `get_my_api_usage`

---

## Common Parameters

All tools accept these optional parameters where applicable:

| Parameter | Description | Example |
|-----------|-------------|---------|
| `include` | Enrich response with related data | `participants;events;scores` |
| `select` | Return only specific fields | `id,name,starting_at` |
| `filters` | Filter included data | `fixtureLeagues:501,271` |
| `sortBy` | Sort results by field | `starting_at` |
| `locale` | Translate name fields | `en`, `de`, `fr`, `ar` |
| `page` | Pagination page number | `2` |
| `per_page` | Results per page (max 50) | `25` |
| `timezone` | Timezone for datetimes | `Europe/London` |

### Include examples for fixtures

```
participants;events;scores;state;periods;statistics;lineups;
venue;league;season;round;stage;odds;predictions;referees;
formations;coaches;tvStations;weatherReport;ballCoordinates;
premiumOdds;inplayOdds;prematchNews;postmatchNews;xGFixture
```

---

## Authentication

The server reads your token from `SPORTMONKS_API_TOKEN`. Tokens never expire — manage them at [MySportmonks](https://my.sportmonks.com/api/tokens).

> **Note:** Do not expose your token in frontend code. This MCP server is designed to run server-side.