nikhilkichili/nba-analytics-mcp

NBA Odds MCP Server

A Model Context Protocol (MCP) server that provides NBA basketball odds data from The Odds API.

Overview

This MCP server enables LLMs (Large Language Models) like Claude to access real-time NBA odds data. It provides information about:

• Current NBA games with betting odds
• NBA Championship winner odds
• Team-specific game schedules
• Basic NBA league information

The server acts as a bridge between LLMs and The Odds API, handling authentication, data formatting, and error handling.

Requirements

• Python 3.10 or higher
• The Odds API key (included in the server)
• MCP-compatible client (Claude Desktop, etc.)
• Matplotlib, NumPy, and Pillow for visualizations

Installation

1. Set up Python 3.10 or higher

   # Using pyenv (already set up)
   pyenv local 3.10.13
   

2. Create and activate a virtual environment

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies

   pip install "mcp[cli]" httpx
   

Usage

Running the Server

# Activate the virtual environment
source venv/bin/activate

# Run the server
python nba_odds_server.py

Automated Data Collection

To build a meaningful historical database for trend analysis, set up automated data collection:

1. Create a data collection script (odds_collector.py) in your project directory that collects and stores odds data

2. Set up cron jobs to run this script at regular intervals:

# Daily collection at 7:30 AM
30 7 * * * cd /Users/nikhil/Documents/MCP_test && /Users/nikhil/Documents/MCP_test/venv/bin/python odds_collector.py >> /Users/nikhil/Documents/MCP_test/collection_log.txt 2>&1

# Collection at 3:30 PM (for game days)
30 15 * * * cd /Users/nikhil/Documents/MCP_test && /Users/nikhil/Documents/MCP_test/venv/bin/python odds_collector.py >> /Users/nikhil/Documents/MCP_test/collection_log.txt 2>&1

# Collection at 8:30 PM (for game days and post-game)
30 20 * * * cd /Users/nikhil/Documents/MCP_test && /Users/nikhil/Documents/MCP_test/venv/bin/python odds_collector.py >> /Users/nikhil/Documents/MCP_test/collection_log.txt 2>&1

3. Recommended collection frequency:
   • Daily baseline collection (morning)
   • Pre-game collection on game days (afternoon)
   • Post-game collection for market reactions (evening)

Configuring Claude Desktop

1. Edit the Claude Desktop configuration file:

   ~/Library/Application Support/Claude/claude_desktop_config.json
   

2. Add the following configuration:

   {
     "mcpServers": {
       "nba-odds": {
         "command": "/Users/nikhil/Documents/MCP_test/venv/bin/python",
         "args": [
           "/Users/nikhil/Documents/MCP_test/nba_odds_server.py"
         ]
       }
     }
   }
   

3. Restart Claude Desktop

Testing the Server

Ask questions like:

• "What are the current odds for the NBA Championship?"
• "Show me upcoming NBA games"
• "What team is favored to win the NBA Championship?"
• "Tell me about the NBA games happening today"
• "Simulate a game between the Lakers and the Celtics"

Available Tools

The server provides the following tools:

Basic NBA Data Tools

1. get_nba_info() - Provides basic information about the NBA basketball category

2. get_nba_games(markets, regions) - Gets current NBA games with odds

   • Parameters:
     • markets: Comma-delimited list of markets (h2h, spreads, totals)
     • regions: Comma-delimited list of regions (us, uk, eu, au)

3. get_nba_championship_odds() - Gets current NBA Championship winner odds

4. get_nba_team_stats(team_name) - Gets upcoming games for a specific team

   • Parameters:
     • team_name: Name of the NBA team

Simulation Tools

1. simulate_nba_game(home_team, away_team) - Simulate an NBA game using AI/ML models

   • Parameters:
     • home_team: Name of the home team
     • away_team: Name of the away team

2. simulate_championship_odds() - Simulate NBA championship odds using 1000 season simulations

3. simulate_season_remainder() - Simulate the remainder of the NBA season including playoffs

4. get_simulation_accuracy() - Get the accuracy statistics of previous game simulations

Betting Analysis Tools

1. get_betting_recommendations(max_recommendations) - Get smart betting recommendations based on odds movement and historical trends

   • Parameters:
     • max_recommendations: Maximum number of recommendations to return (default: 3)

2. analyze_team_ats_performance(team_name) - Analyze a team's performance against the spread (ATS)

   • Parameters:
     • team_name: Name of the NBA team to analyze

3. analyze_odds_movement(event_id, days) - Analyze how betting odds have moved for a specific game

   • Parameters:
     • event_id: Event identifier
     • days: Number of days to look back (default: 7)

NBA Trivia Game Tools

1. start_nba_quiz(category, difficulty, length) - Start a new NBA trivia quiz game

   • Parameters:
     • category: Category of questions (random, nba_history, current_nba, nba_stats, nba_rules, championships)
     • difficulty: Difficulty level (rookie, veteran, all-star, hall-of-fame, mixed)
     • length: Number of questions (default: 5)

2. answer_quiz_question(quiz_id, answer) - Answer a question in an active trivia quiz

   • Parameters:
     • quiz_id: ID of the active quiz
     • answer: The answer selected by the user

3. get_daily_nba_question() - Get the daily NBA trivia question

4. answer_daily_nba_question(answer) - Answer the daily NBA trivia question

   • Parameters:
     • answer: The answer selected by the user

5. get_nba_quiz_stats() - Get statistics about NBA trivia quiz performance

Line Movement Analysis Tools

1. analyze_reverse_line_movement(days) - Analyze reverse line movement patterns from historical odds data

   • Parameters:
     • days: Number of days of historical data to analyze (default: 30)

2. analyze_sharp_money_action(days, threshold) - Identify games with potential sharp money action

   • Parameters:
     • days: Number of days to analyze (default: 30)
     • threshold: Minimum probability change to consider (default: 3%)

3. calculate_betting_strategy_roi(movement_type, days) - Calculate historical ROI for betting strategies based on line movements

   • Parameters:
     • movement_type: Type of movement to analyze (reverse, sharp)
     • days: Number of days to analyze (default: 90)

4. create_line_movement_chart(game_id, team_name, days) - Create a chart showing probability impact of line movements

   • Parameters:
     • game_id: Optional specific game to analyze (use "help" to see available games)
     • team_name: Optional team name to filter by
     • days: Number of days to analyze if no specific game/team

Odds Tracking & Analysis Tools

5. analyze_championship_odds_trend(team_name, days) - Analyzes how a team's championship odds have changed over time

   • Parameters:
     • team_name: Name of the NBA team to analyze
     • days: Number of days to look back (default: 30)

6. get_team_odds_history(team_name, days) - Gets historical championship odds data for a specific team

   • Parameters:
     • team_name: Name of the NBA team
     • days: Number of days of historical data to retrieve (default: 30)

7. get_odds_tracking_stats() - Gets statistics about the tracked odds data in the database

Visualization Tools

8. generate_team_odds_chart(team_name, days) - Creates a chart showing championship odds movement for a team

   • Parameters:
     • team_name: Name of the NBA team to chart
     • days: Number of days to include in the chart (default: 30)

9. generate_teams_comparison_chart(team_names, days) - Creates a chart comparing championship odds for multiple teams

   • Parameters:
     • team_names: Comma-separated list of team names to compare
     • days: Number of days to include in the chart (default: 30)

10. generate_game_odds_chart(event_id) - Creates a chart showing odds movement for a specific game

    • Parameters:
      • event_id: ID of the game/event to chart

11. generate_bookmaker_comparison_chart(team_name, days) - Creates a chart comparing odds from different bookmakers

    • Parameters:
      • team_name: Name of the NBA team to analyze
      • days: Number of days to include in the chart (default: 30)

Data Storage and Visualization

SQLite Database

The server uses SQLite to store historical odds data, enabling trend analysis:

• Championship Odds Table: Tracks team championship odds over time
• Game Odds Table: Tracks individual game odds and line movements
• Automatic Storage: All API requests automatically store data in the database

Visualization System

The server includes a robust visualization system powered by Matplotlib:

• Charts Directory: All generated charts are saved to a charts folder
• Base64 Embedding: Charts are returned as base64-encoded images for display in LLM responses
• Chart Types:
  • Team odds trend charts
  • Multi-team comparison charts
  • Game odds movement charts
  • Bookmaker comparison charts

Data Analysis

The system provides automated analysis of odds data:

• Trend detection (improvement, decline, stability)
• Bookmaker discrepancy analysis
• Historical odds movement patterns
• Visual indicators of significant odds shifts

API Information

This server uses The Odds API (https://the-odds-api.com/) with the following endpoints:

• GET /sports - List all sports categories
• GET /sports/{sport_key}/odds - Get odds for a specific sport
• GET /sports/{sport_key}/events/{event_id}/odds - Get odds for a specific event

API key is included in the server configuration.

Troubleshooting

• Server not starting: Ensure Python 3.10+ is installed and the virtual environment is activated
• MCP client not connecting: Check the configuration file path and format
• API errors: Verify API key validity and check for rate limiting

License

This project is for educational purposes.

Acknowledgements

• The Odds API for providing sports betting data
• Model Context Protocol (MCP) for the server framework