Skip to main content
Glama
IPL MCP Server

IPL MCP Server

by jay-arora31

IPL MCP Server

A Model Context Protocol (MCP) server that provides natural language access to IPL (Indian Premier League) cricket match data. Built using data from Cricsheet with an enhanced sample of 18 IPL matches including Virat Kohli games and CSK vs MI classics.

šŸ Features

  • Natural Language Queries: Ask questions about IPL data in plain English

  • Enhanced Dataset: 18 carefully selected IPL matches including:

    • Virat Kohli batting performances (99 runs in 4 matches)

    • CSK vs MI classic encounters (3 matches)

    • All major IPL teams represented

  • Rich Analytics: Player stats, team performance, match analysis

  • Claude Desktop Integration: Works seamlessly with Claude Desktop

  • Fast SQL Backend: Efficient SQLite database with optimized queries

  • Extensible: Can easily be extended to work with the full 1,169+ match dataset

Related MCP server: cricket-mcp

šŸš€ Quick Start

Prerequisites

  • Python 3.11+

  • uv package manager

  • Claude Desktop (for MCP integration)

Installation

  1. Clone and setup:

git clone <your-repo>
cd ipl-mcp-server
  1. Install dependencies:

uv install
  1. Setup database and load data:

uv run python main.py --setup --data-dir data_small

This will:

  • Create SQLite database tables

  • Process 18 sample JSON match files (includes V Kohli & CSK vs MI)

  • Calculate player and team statistics

  • Takes ~10-15 seconds to complete

  1. Test the queries (optional):

uv run python test_queries.py
  1. Start the MCP server:

uv run python main.py --server

šŸŽÆ Example Queries

Basic Match Information

  • "Show me all matches in the dataset"

  • "How many matches are in the database?"

  • "Which team won the most matches?"

  • "What was the highest total score?"

  • "Show matches played in Mumbai"

Player Performance

  • "Who scored the most runs across all matches?"

  • "Which bowler took the most wickets?"

  • "Show me Virat Kohli's batting stats"

  • "Who has the best bowling figures in a single match?"

  • "Show all centuries scored"

Advanced Analytics

  • "What's the average first innings score?"

  • "Which venue has the highest scoring matches?"

  • "What's the most successful chase target?"

  • "Which team has the best powerplay performance?"

  • "Show me partnership records over 100 runs"

Match-Specific Queries

  • "Show me the scorecard for match between CSK and MI"

  • "How many sixes were hit in the final?"

  • "What was the winning margin in the closest match?"

šŸ”§ Claude Desktop Integration

  1. Add to Claude Desktop config:

Edit your Claude Desktop MCP configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ipl-cricket-server": {
      "command": "uv",
      "args": ["run", "python", "main.py", "--server"],
      "cwd": "/path/to/your/ipl-mcp-server"
    }
  }
}
  1. Restart Claude Desktop

  2. Test the connection: Ask Claude: "Show me IPL team statistics"

šŸ“Š Database Schema

The server uses SQLite with the following key tables:

  • matches: Match metadata (teams, venue, date, outcome)

  • innings: Innings-level data (totals, wickets, overs)

  • deliveries: Ball-by-ball data (runs, wickets, extras)

  • player_stats: Aggregated batting/bowling statistics

  • team_stats: Team performance metrics

  • players: Player registry with Cricsheet IDs

  • teams: Team information

šŸ› ļø Advanced Usage

Command Line Options

# Setup database (first time only)
uv run python main.py --setup

# Reset database and reload data
uv run python main.py --reset

# Start server (default)
uv run python main.py --server

# Custom data directory
uv run python main.py --setup --data-dir /path/to/data

API Integration

The server can be extended to work with other MCP clients beyond Claude Desktop. The query engine supports pattern matching for natural language understanding.

Adding Custom Queries

Extend the QueryEngine class in src/mcp_server/query_engine.py:

{
    'pattern': r'your.*query.*pattern',
    'handler': self.your_handler_method,
    'description': 'Your query description'
}

šŸ“ˆ Performance

  • Database Size: ~3MB for 18 sample matches

  • Setup Time: 10-15 seconds for data load

  • Query Response: <1 second for most queries

  • Memory Usage: ~50MB typical runtime

šŸš€ Scaling to Full Dataset

The system can easily handle the complete 1,169 match dataset:

  • Full Database Size: ~50MB

  • Full Setup Time: 2-3 minutes

  • Simply use --data-dir data instead of --data-dir data_small

šŸ” Sample Query Results

Query: "Which team won the most matches?"

šŸ“Š **Team with most wins**

1. Mumbai Indians | 120 wins | 203 matches | 59.11% win rate
2. Chennai Super Kings | 118 wins | 195 matches | 60.51% win rate
3. Royal Challengers Bangalore | 88 wins | 203 matches | 43.35% win rate
...

Query: "Show me Virat Kohli batting stats"

šŸ **V Kohli** Batting Stats:
• Total Runs: 99
• Matches: 4  
• Highest Score: N/A
• Average: 24.75
• Strike Rate: 117.86
• Sixes: 4
• Fours: 8

šŸ—„ļø Data Source

All data comes from Cricsheet, which provides:

  • Ball-by-ball data for IPL matches from 2008-2017 seasons (enhanced sample of 18 matches)

  • Player registry with unique identifiers

  • Match metadata including officials, venues, outcomes

  • JSON format with comprehensive match details

  • Full dataset available: 1,169+ matches (2008-2024) can be loaded by using --data-dir data

šŸ¤ Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Add your improvements

  4. Test with sample queries

  5. Submit a pull request

šŸ“ License

This project is licensed under the MIT License. Data provided by Cricsheet under their terms of use.

šŸš€ Working with Full Dataset

To use the complete 1,169 match dataset instead of the sample:

  1. Reset and load full data:

uv run python main.py --reset --data-dir data

āš ļø This will take 2-3 minutes to complete

  1. Benefits of full dataset:

  • Complete IPL history (2008-2024)

  • More accurate player statistics

  • Comprehensive team performance data

  • Better trend analysis capabilities

āœ… Verify Installation

Test your setup with these commands:

# Quick database check
uv run python -c "from src.database.database import get_db_session; from src.database.models import *; session = get_db_session(); print(f'āœ… Database ready: {session.query(Match).count()} matches loaded')"

# Test natural language query
uv run python -c "from src.mcp_server.query_engine import QueryEngine; print(QueryEngine().process_query('how many matches'))"

# Run interactive demo
uv run python test_queries.py

Built with ā¤ļø for cricket analytics and AI-powered data exploration

Available Tools

1 tool
query_ipl_dataC

Query IPL cricket data using natural language. Examples: - 'Show me all matches in the dataset' - 'Which team won the most matches?' - 'Who scored the most runs across all matches?' - 'What was the highest total score?' - 'Show matches played in Mumbai' - 'Who has the best bowling figures?' - 'Show me Virat Kohli batting stats' - 'What's the average first innings score?' - 'Show me all centuries scored' - 'Which venue has the highest scoring matches?'

Inputs: query (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of ambiguity or overlap between tools. The single tool 'query_ipl_data' has a clearly defined purpose that cannot be confused with any other tool in this server.

    Naming Consistency5/5

    The single tool name 'query_ipl_data' follows a clear verb_noun pattern. With only one tool, naming consistency is inherently perfect as there are no other tools to compare against or create inconsistencies with.

    Tool Count2/5

    A single tool for an IPL cricket data server feels too thin for the apparent scope. The examples suggest complex queries about matches, players, venues, and statistics, which would typically require multiple specialized tools for a complete interface. One tool attempting to handle all these diverse queries through natural language is insufficient for proper domain coverage.

    Completeness2/5

    The server appears to cover IPL cricket data, but with only one natural language query tool, the surface is severely incomplete. There are no dedicated tools for specific operations like retrieving match details, player statistics, team information, or venue data. The single tool approach creates significant gaps that will likely cause agent failures when trying to perform structured operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables querying log data stored in SQLite databases through the Model Context Protocol, allowing natural language interactions with log analysis.
      -
    • F
      license
      Not graded
      quality
      B
      maintenance
      An MCP server that enables natural language querying of over 10 million ball-by-ball cricket deliveries stored in a local DuckDB database. It provides 26 tools for analyzing player matchups, situational stats, and historical records across all major cricket formats and tournaments.
      3
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with SQLite databases by executing read and write queries, listing tables, and inspecting schemas. It provides a secure, local interface for database management and data retrieval through the Model Context Protocol.
      2
      MIT