MCP tools

Every tool the MCP server at https://api.badmintonapi.com/mcp offers, built from the same list the API runs on, so this page and the server can never disagree. Each tool calls the endpoint beside it with your key: its plan, its limits and its answer are that endpoint's. Setup is in MCP for AI assistants.

You rarely need to name a tool yourself. Ask your assistant a question in plain words and it chooses: a question about a player usually starts with search to find the id, then reads the player's matches, rivals or titles. Naming a tool helps when you want a particular view, such as "use win_chance for these two players on the date of the 2024 final".

What a tool call looks like

Under the hood, an assistant sends a JSON-RPC tools/call with the tool's name and its arguments, which are the endpoint's parameters. You can make the same call with curl to see exactly what the assistant sees.

Calling a tool with curl

curl -s https://api.badmintonapi.com/mcp \
  -H "Authorization: Bearer $BADMINTON_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"search","arguments":{"q":"axelsen"}}}'

Questions that work well

"List every final Viktor Axelsen has played since 2020."
"Who won the 2023 World Championships men's doubles?"
"What was the world number one in women's singles on 1 May 2019?"
"Give me tomorrow's matches with start times in Bangkok time."
"What chance does our rating give An Se-young against Chen Yufei?"

Good habits

Ask for ids to be kept across a conversation, so the assistant does not search for the same player twice. Ask for a date when the question is about the past ("as of the 2022 All England"), since rankings and ratings move every week. Tools above your plan answer with the plan that has them rather than failing silently, so an assistant on a Free key will tell you when a question needs the Archive or Odds plan. The list below is every tool, with the plan its endpoint comes with and the parameters it takes.

What a tool returns

A tool's answer is the endpoint's JSON, the same data and meta the API gives, passed to the assistant as text. Notes about held-back fields reach the assistant too, so it knows when a value is missing because of your plan rather than because it is not known.

Every tool

yesterdays_resultsFree key: Every match finished yesterday (UTC), with scores and closing prices. Calls /v1/results/yesterday.
results_on_dateFree key: Matches finished on a day. The free key covers yesterday and today; Archive covers every day held. Calls /v1/results. datediscipline
upcoming_matchesFree key: Matches scheduled next and those under way, soonest first. Calls /v1/fixtures. discipline
searchFree key: Find players, pairs, tournaments, series, countries, venues and cities by name, in one call. Accents and capitals do not matter; "Name / Name" finds both players of a pair; a year picks that edition. Calls /v1/search. qkindlimit
list_countriesFree key: Every country with players held: players, active players, and titles by discipline. Calls /v1/countries.
country_profileArchive: One country by its IOC code: titles by discipline, its most successful players, recent titles and the editions it hosted. Calls /v1/countries/{code}.
season_calendarFree key: A year's tournaments in date order, with dates, city, venue, prize money and whether each is finished, in progress or upcoming. Calls /v1/calendar. yearserieslevel
find_venuesArchive: Arenas that have staged tournaments held, most editions first, by country, city or name, with their height above sea level. Calls /v1/venues. countrycityq
host_citiesArchive: Host cities, most editions first, with their venues and the years they staged tournaments. Calls /v1/locations. countryq
roll_of_honourArchive: The roll of honour of a series: champions and runners-up in every event, year by year, with the players who won it most in meta. Calls /v1/series/{slug}/champions. discipline
find_tournamentsArchive: Tournament editions, newest first, with the disciplines and match counts of each. Calls /v1/tournaments. seriesyearlevel
tournament_drawArchive: A whole draw, first round to final, with seeds, scores and closing prices where held. Calls /v1/tournaments/{id}/draw. disciplinesport_class
team_tiesArchive: A team event (Thomas, Uber, Sudirman Cup): every tie with its nations, score, date and venue, and the matches inside it. Calls /v1/tournaments/{id}/ties. stage
find_matchesArchive: Draw matches by player, tournament, series, year, discipline and round. Calls /v1/matches. playertournamentseriesyeardisciplineroundwith_odds
find_playerArchive: Players by name, country (IOC code) and gender, most matches first. Calls /v1/players. qcountrygender
player_matchesArchive: A player's draw matches, newest first. Calls /v1/players/{id}/matches. yeardiscipline
player_partnersArchive: A player's doubles partners, most matches together first, with wins and titles as a pair. Calls /v1/players/{id}/partners. discipline
player_opponentsArchive: The players met most often, with wins and losses against each and the last meeting. Calls /v1/players/{id}/opponents. disciplinelimit
player_titlesArchive: Every final a player reached, won or lost, newest first, with partner, opponents and score; totals by discipline in meta. Calls /v1/players/{id}/titles. discipline
player_formArchive: A player's latest results, newest first, with the record over them and the winning or losing run they are on. Calls /v1/players/{id}/form. disciplinelast
player_statsArchive: Game statistics from every score held: games and points won, deciding games, extended games (20-all and beyond), comebacks after losing the first game, retirements. Calls /v1/players/{id}/stats. disciplinefromto
player_scheduleArchive: How hard a player's calendar has been: each event played, newest first, with dates, matches, how far they went and the rest days before it; in meta, days since the last event, events and matches in the last 30 to 90 days and back-to-back weeks, as they stood on any day. Calls /v1/players/{id}/schedule. disciplinedatelast
player_ranking_historyArchive: A player's world ranking over time, list by list, newest first: every list from September 2026, and the weekly top lists back to 2013 for weeks they were in them. Calls /v1/players/{id}/rankings. discipline
head_to_headArchive: Every meeting of two players, singles or doubles, with the wins of each. Calls /v1/h2h. player1player2
world_rankingsArchive: The world ranking for a discipline, the latest or as it stood on a date: every ranked player from September 2026, and for earlier dates back to 2013 the week's top list (about 20 to 25 places; meta.full says which). Calls /v1/rankings. disciplinedate
world_number_onesArchive: Every world number one since the computer ranking began on 1 October 2009: each reign with its dates and weeks, by discipline, on a date, or for one player. Calls /v1/rankings/number-ones. disciplinedateplayer
player_ratingsArchive: Our own rating (Elo-style, from every senior result) as a table for a discipline on any date, or one player's rating history. Not an official BWF figure. Calls /v1/ratings. disciplinedateplayeractive
win_chanceOdds: The chance each side wins from our rating, with a fair price and their head-to-head. Singles or doubles, on any date. Calls /v1/predict. player1player2partner1partner2disciplinedatehostgames
biggest_upsetsOdds: The biggest upsets: winners at the longest closing prices, or with the lowest chance by our rating. Calls /v1/analysis/upsets. bydisciplinefromtolimit
seed_performanceArchive: How seeds perform: for each seed, how often they reach the semi-final and final and win the title, and seeded against unseeded round by round. Calls /v1/analysis/seeds. disciplinefromto
deciding_gamesArchive: How often matches go to a third game, how often the first-game loser wins, points per game and extended games, by decade or year. Calls /v1/analysis/deciders. bydisciplinefromto
recordsArchive: Records: most titles, most finals, longest winning runs, widest winning margins and most points in a match. Calls /v1/analysis/records. typedisciplinefromtolimit
market_accuracyOdds: How accurate the closing market is: favourites' expected and actual win rate by price band, by round and by seeding, the return at the closing price, and each bookmaker's average margin. Calls /v1/analysis/market. disciplinefromto
match_oddsOdds: Opening and closing prices, bookmaker by bookmaker, for a draw match (mt_) or a results match (ev_): the match winner, and the handicap and total lines in games and points. Calls /v1/odds/{id}.
backtest_strategyOdds: Run a simple strategy over every settled match with closing prices: strike rate, return and how far it is from chance. Calls /v1/backtest. strategydisciplineroundfromtomin_pricemax_price
live_scoresLive: Matches under way now, with the score so far. Calls /v1/live.
match_pointsArchive: Point by point: every rally of a match, game by game, with the score after it, who won it and who served it, and each side's points won on and against serve and longest run. A match in play needs the Live plan. Rallies are being read for every finished match held, newest first. Calls /v1/events/{id}/points.