# TheSportsDB Global Sports Database MCP > TheSportsDB Global Sports Database provides API access to structured metadata for global sports. Use your AI agent to search teams, players, and leagues across hundreds of sports. It retrieves current standings, upcoming match schedules, player career histories (honours/contracts), and detailed team profiles in one place. ## Overview - **Category:** knowledge-management - **Price:** Free - **Tags:** sports-data, metadata, league-standings, athlete-profiles, match-schedules, historical-data ## Description You'll find that TheSportsDB provides structured data access to professional sports across the globe, letting your AI agent pull together metrics you otherwise have to track manually. You don't need to jump between separate league sites; this server gathers everything into actionable tools. **Finding Your Scope and Entities** You can start broad by calling `list_all_sports` to see every sport tracked in the database, or use `list_all_leagues` to get a list of all available leagues. Once you know your area, you'll need the league ID to narrow things down. You can call `get_league_details` with a League ID to pull metadata like the official name and description for that specific league. If you want to see every team in play within one competition, use `list_all_teams_in_league`; otherwise, you can pinpoint teams using `search_teams`, which locates sports clubs by name across global databases. When you need athlete profiles, run `search_players` to find specific players by name and pull their basic profile details. **Tracking Performance and Scheduling** To track a team's current standing or points table for any season, call `get_league_table`. If you just want to know what’s happening in the league generally, run `list_events_by_season` to get every recorded match that happened during a defined league period. For real-time planning, use `list_next_events_by_team` to predict and list upcoming matches for any given team, including opponents and dates. Conversely, if you want to review recent action, run `list_last_events_by_team` to get a chronological rundown of that team’s latest match results and scores. You can also search generally across the entire database using `search_events` by name or keyword for any sports event. **Deep Player History and Career Metrics** Building an athlete's full career profile requires several tool calls. To track a player’s history, you'll use `list_former_teams` to list every club they played for throughout their professional life. For accolades, call `list_player_honours`; this retrieves all major trophies, awards, and championships the athlete has won. You can also pull structured data on an athlete's contracts—both current and past—using `list_player_contracts`. To understand key personal achievements, like most goals scored or best attendance record, use `list_player_milestones` to retrieve those specific records for any player. **Daily Events and General Search** If you’re planning around a single day of play, call `list_events_by_day` to find every sports match scheduled for that precise date. You can also narrow down historical matches using `list_events_by_season`, which retrieves all recorded events within a specific league period. For comprehensive global data gathering, your agent uses the core search tools—`search_players`, `search_teams`, and `search_events`—to locate entities across different leagues before pulling detailed metrics on performance or history. ## Tools ### get_league_details Retrieves metadata (like league name, description) using a specific League ID. ### get_league_table Fetches the current standings and points table for an entire season of a specified league. ### list_all_leagues Returns a list of all available sports leagues in the database, helping you find your starting point. ### list_all_sports Lists every sport tracked by TheSportsDB, letting you scope your search globally. ### list_all_teams_in_league Gives a roster of all teams that belong to one particular league ID. ### list_events_by_day Finds and lists every sports event or match scheduled for a specific date. ### list_events_by_season Retrieves all recorded events (matches) that happened within a defined league season. ### list_former_teams Tracks an athlete's career path by listing every previous club or team they played for. ### list_last_events_by_team Gets a chronological list of recent match results and scores for one specific team. ### list_next_events_by_team Predicts and lists upcoming matches, including opponents and dates, for a given team. ### list_player_contracts Gets structured details about an athlete's current or past professional contracts. ### list_player_honours Lists all major trophies, awards, and accolades won by a specific player in their career. ### list_player_milestones Retrieves key personal records or achievements for an athlete (e.g., most goals, best attendance). ### search_events Searches for sports events by a general name or keyword across the database. ### search_players Finds specific athletes using their name, and retrieves their basic profile details. ### search_teams Locates sports teams by name across different leagues and global databases. ## Prompt Examples **Prompt:** ``` Search for the professional profile of 'Lionel Messi'. ``` **Response:** ``` I've fetched Messi's profile. He is a forward for Inter Miami CF (ID: 34145937). I have his detailed bio, height, weight, and official social media links. Would you like to see his career honours cabinet? ``` **Prompt:** ``` Show me the current standings table for the NBA season 2023-2024. ``` **Response:** ``` Running the standings query... I've retrieved the full NBA table. Notable leaders include the Boston Celtics in the East and OKC Thunder in the West. Would you like the specific points and win/loss records for a particular team? ``` **Prompt:** ``` What are the next 5 matches scheduled for 'Arsenal'? ``` **Response:** ``` Inspecting the calendar... Arsenal has 5 upcoming fixtures. The next match is against Everton at the Emirates Stadium. I also found matches against Brighton and Bournemouth. Would you like the precise start times? ``` ## Capabilities ### Search for Athletes and Teams Locate specific players or teams by name using `search_players` and `search_teams`. ### Retrieve League Standings Get the current points table and standings for any specified league season via `get_league_table`. ### Plan Event Schedules List upcoming matches or past match results for a given team using `list_next_events_by_team` or `list_last_events_by_team`. ### Analyze Player Career Data Gather an athlete's full history, including trophies (`list_player_honours`), contracts, and previous clubs (`list_former_teams`). ### Identify League Scope Find out what leagues or sports are available in the database by calling `list_all_leagues` or `list_all_sports`. ## Use Cases ### Building a Player Biography Report A journalist needs to write about a player’s career peak. They ask their agent: 'Gather all of Messi's major awards, his last five matches, and list every club he played for.' The agent executes `list_player_honours`, `list_last_events_by_team`, and `list_former_teams` sequentially, giving the journalist a single, comprehensive data package. ### Fantasy Draft Prep A fantasy manager needs to compare two players. They instruct their agent to 'Compare Player A and Player B.' The agent uses `search_players` first to get IDs, then runs `list_player_milestones` on both, allowing the manager to see who has more career records instantly. ### Analyzing League Shifts A betting analyst wants to know how a league's structure changed. They call `list_all_leagues`, find the target competition, and then use `get_league_table` for multiple seasons by calling `list_events_by_season` over time periods. ### Live Team Status Check A team operations manager needs to know if their club has a gap in its schedule. They run `search_teams` to confirm the ID, then use `list_next_events_by_team` and `list_last_events_by_team` back-to-back to get full operational visibility. ## Benefits - Get immediate, structured data on league rankings using `get_league_table`. You don't have to calculate points manually; the tool returns the full table ready for analysis. - Track an athlete’s entire professional journey. By running `list_former_teams` and `list_player_honours`, you build a complete, verifiable history of their career in minutes. - Never miss an upcoming match detail again. Use `list_next_events_by_team` to pull the next 5 fixtures for any team right into your workflow. - Quickly scope out data needs by calling `list_all_leagues`. This tells you exactly which ID you need before attempting a complex query like `get_league_details`. - Automate content gathering. For media, use `list_last_events_by_team` to pull recent scores and results without needing to visit the league's dedicated news page. ## How It Works The bottom line is that you don't write complex multi-step API calls; your AI client just runs the right tool in the correct sequence for you. 1. First, determine your scope. Use `list_all_sports` to find the sport, then use `list_all_leagues` and `get_league_details` to pinpoint the exact league ID. 2. Next, run the specific query: are you checking standings? Call `get_league_table`. Are you tracking a player's recent performance? Use `list_last_events_by_team` with the necessary team IDs. 3. Your agent processes the data and returns structured JSON containing all requested metadata—be it scores, standings, or biographical details. ## Frequently Asked Questions **How do I find out what leagues are available using list_all_leagues?** Call `list_all_leagues` first. It returns a full list of every league ID and name tracked by the server, so you know exactly which one to target next. **Can I get current team standings using get_league_table?** Yes, `get_league_table` pulls the live standings for a specific league and season. You must provide the correct League ID to make it work. **What is the best way to track an athlete's career history? Use list_player_honours or list_former_teams?** Use both tools for a full picture. `list_former_teams` shows where they played; `list_player_honours` shows what awards they won while there. **How do I find out the next match schedule for my favorite team?** Use `list_next_events_by_team`. Just provide the team's ID, and it returns a list of their upcoming fixtures with dates and opponents. **Can I search for player details by name using search_players?** Yes. `search_players` finds athletes by name, giving you their initial profile data and ID needed to run deeper queries like `list_player_milestones`. **If I need to check basic information about a small or niche competition, should I use `list_all_leagues` or `get_league_details`?** You must use `get_league_details`. This tool retrieves metadata for one specific league ID. It lets you verify if a league exists and pull key information even if it doesn't have current standings data. **What happens if I run multiple queries, like checking both `list_last_events_by_team` and `list_next_events_by_team`, in rapid succession?** The system processes these requests sequentially. Using both tools gives you the full picture: past results provide scores and opponent history; future events give dates and times for upcoming matches. **How does the server handle rate limits or invalid API keys when I try to use any tool like `list_all_sports`?** The server will return a specific HTTP error code and message detailing the failure. You must confirm your API Key is correctly configured in your AI client's settings before running the command. **Can my AI find the history and official badge of a specific team just by its name?** Yes! Use the `search_teams` tool with the team name. Your agent will respond with complete metadata, founded year, and high-resolution badge URLs in seconds. **How do I check the current standings for a major league like the Premier League?** Simply ask the agent to run the `get_league_table` tool providing the League ID (e.g., 4328 for Premier League) and the current season. It will compile the full standings with points and goal differences. **Does the integration provide video highlights for recent match events?** Yes. Many event results retrieved via tools like `list_last_events_by_team` include a `strVideo` field which contains direct YouTube links to official match highlights when available.