ipl-mcp

MCP server for querying IPL cricket data. 19 seasons of ball-by-ball data (2008-2026) — 280K+ deliveries, 1000+ matches.

The database is automatically downloaded and kept up to date from overgraph.in.

Usage

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "ipl": {
      "command": "npx",
      "args": ["-y", "ipl-mcp"]
    }
  }
}

Claude Code

Add to your .mcp.json:

{
  "mcpServers": {
    "ipl": {
      "command": "npx",
      "args": ["-y", "ipl-mcp"]
    }
  }
}

Tools

query

Run any SQL query against the IPL database (DuckDB dialect).

"Who scored the most runs in IPL history?"
→ SELECT player, runs, matches, strike_rate FROM player_career_stats ORDER BY runs DESC LIMIT 10

player_profile

Get a comprehensive player profile in one call — career stats, best season, phase breakdown, top venues, top opponents, and dismissal patterns. Supports fuzzy name matching.

"Tell me about Klaasen" → player_profile("Klaasen")

team_season

Full team season summary — W/L record, top run scorers, top wicket takers, highest totals, and Player of the Match awards. Omit season for all-time summary.

"How did CSK do in 2024?" → team_season("CSK", "2024")

head_to_head_teams

Complete rivalry summary between two IPL teams — overall record, last 5 results, top performers, and biggest wins.

"MI vs CSK rivalry" → head_to_head_teams("Mumbai", "Chennai")

match_of_the_day

Returns a random classic IPL match — picks from last-ball wins, centuries, super overs, and highest chases. Great for trivia or nostalgia.

compare_players

Side-by-side comparison of two players — career stats, phase breakdown, batting positions, and head-to-head (if they've bowled to each other).

"Kohli vs Rohit" → compare_players("Kohli", "Rohit")

list_tables

Lists all available tables with column names and types.

Available Tables

| Table | Description | |-------|------------| | matches | Match metadata — date, venue, teams, winner, toss | | deliveries | Ball-by-ball data — batter, bowler, runs, wickets | | batting_scorecard | Per-innings batting stats | | bowling_scorecard | Per-innings bowling stats | | partnerships | Batting partnerships by wicket | | match_summary | Team totals per match | | player_career_stats | Career aggregates | | player_season_stats | Per-season aggregates | | player_batting_phase_stats | Batting by phase (powerplay/middle/death) | | player_bowling_phase_stats | Bowling by phase | | player_position_stats | Batting by position | | player_venue_stats | Per-venue performance | | player_opponent_stats | Per-opponent performance | | player_dismissal_stats | Dismissal type breakdown | | head_to_head | Batter vs bowler career records | | venue_stats | Venue averages and tendencies | | venue_team_record | Team record at each venue | | venue_season_stats | Venue trends by season | | match_players | Squad lists per match | | players | Player name/ID registry |

Data Updates

The database is updated from Cricsheet data. When new matches are added, the MCP server automatically downloads the latest version on next startup.

Data is cached locally at ~/.ipl-mcp/.

License

MIT