Badminton, for your AI assistant.
37 tools any MCP client can call. Ask in plain words: your assistant finds the ids, picks the tool and reads the answer. Same key, plan and limits as the API.
https://api.badmintonapi.com/mcp- Streamable HTTP, JSON-RPC by POST
- Your key as
Authorization: Bearer - Every tool is read-only
Connect
Get a key
Sign in with Google and a free key is made at once. The free key reaches 6 of the tools; each plan above it opens more.
Claude Code
One command, with your key in place of YOUR_KEY.
claude mcp add --transport http badminton \
https://api.badmintonapi.com/mcp \
--header "Authorization: Bearer YOUR_KEY"Cursor and other clients
Add this to the client's MCP settings file. Any client that can send a header on a remote server works.
{
"mcpServers": {
"badminton": {
"url": "https://api.badmintonapi.com/mcp",
"headers": {
"Authorization": "Bearer YOUR_KEY"
}
}
}
}Plain questions, real answers.
Your assistant chooses the tools. These are the ones each question needs, most of them after a search for the ids.
“Who has won the most All England men's singles titles?”
roll_of_honour“How has Viktor Axelsen done against Kodai Naraoka?”
searchhead_to_head“What is on court today, and what finished yesterday?”
upcoming_matchesyesterdays_results“Who are the best rated women's doubles pairs right now?”
player_ratings“How often do the top seeds win a Super 1000?”
seed_performance“Which finals went to a third game most often?”
deciding_games
37 tools, one for each question worth asking.
Each tool is one API endpoint, with the same parameters and the same answer: data and meta. The documentation has every field.
Search and countries3
-
searchFree keyFind 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.
qkindlimit -
list_countriesFree keyEvery country with players held: players, active players, and titles by discipline.
-
country_profileArchiveOne country by its IOC code: titles by discipline, its most successful players, recent titles and the editions it hosted.
code
Results and calendar4
-
yesterdays_resultsFree keyEvery match finished yesterday (UTC), with scores and closing prices.
-
results_on_dateFree keyMatches finished on a day. The free key covers yesterday and today; Archive covers every day held.
datedisciplinepageper_page -
upcoming_matchesFree keyMatches scheduled next and those under way, soonest first.
disciplinepageper_page -
season_calendarFree keyA year's tournaments in date order, with dates, city, venue, prize money and whether each is finished, in progress or upcoming.
yearserieslevel
Tournaments and draws5
-
roll_of_honourArchiveThe 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.
slugdiscipline -
find_tournamentsArchiveTournament editions, newest first, with the disciplines and match counts of each.
seriesyearlevelpageper_page -
tournament_drawArchiveA whole draw, first round to final, with seeds, scores and closing prices where held.
iddisciplinesport_class -
team_tiesArchiveA team event (Thomas, Uber, Sudirman Cup): every tie with its nations, score, date and venue, and the matches inside it.
idstage -
find_matchesArchiveDraw matches by player, tournament, series, year, discipline and round.
playertournamentseriesyeardisciplineroundwith_oddspageper_page
Players10
-
find_playerArchivePlayers by name, country (IOC code) and gender, most matches first.
qcountrygenderpageper_page -
player_matchesArchiveA player's draw matches, newest first.
idyeardisciplinepageper_page -
player_partnersArchiveA player's doubles partners, most matches together first, with wins and titles as a pair.
iddiscipline -
player_opponentsArchiveThe players met most often, with wins and losses against each and the last meeting.
iddisciplinelimit -
player_titlesArchiveEvery final a player reached, won or lost, newest first, with partner, opponents and score; totals by discipline in meta.
iddiscipline -
player_formArchiveA player's latest results, newest first, with the record over them and the winning or losing run they are on.
iddisciplinelast -
player_statsArchiveGame statistics from every score held: games and points won, deciding games, extended games (20-all and beyond), comebacks after losing the first game, retirements.
iddisciplinefromto -
player_scheduleArchiveHow 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.
iddisciplinedatelast -
player_ranking_historyArchiveA 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.
iddiscipline -
head_to_headArchiveEvery meeting of two players, singles or doubles, with the wins of each.
player1player2
Rankings and ratings4
-
world_rankingsArchiveThe 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).
disciplinedatepageper_page -
world_number_onesArchiveEvery 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.
disciplinedateplayer -
player_ratingsArchiveOur 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.
disciplinedateplayeractivepageper_page -
win_chanceOddsThe chance each side wins from our rating, with a fair price and their head-to-head. Singles or doubles, on any date.
player1player2partner1partner2disciplinedatehostgames
Venues and cities2
-
find_venuesArchiveArenas that have staged tournaments held, most editions first, by country, city or name, with their height above sea level.
countrycityqpageper_page -
host_citiesArchiveHost cities, most editions first, with their venues and the years they staged tournaments.
countryqpageper_page
Odds and analysis7
-
biggest_upsetsOddsThe biggest upsets: winners at the longest closing prices, or with the lowest chance by our rating.
bydisciplinefromtolimit -
seed_performanceArchiveHow 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.
disciplinefromto -
deciding_gamesArchiveHow often matches go to a third game, how often the first-game loser wins, points per game and extended games, by decade or year.
bydisciplinefromto -
recordsArchiveRecords: most titles, most finals, longest winning runs, widest winning margins and most points in a match.
typedisciplinefromtolimit -
market_accuracyOddsHow 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.
disciplinefromto -
match_oddsOddsOpening 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.
id -
backtest_strategyOddsRun a simple strategy over every settled match with closing prices: strike rate, return and how far it is from chance.
strategydisciplineroundfromtomin_pricemax_price
Live2
-
live_scoresLiveMatches under way now, with the score so far.
-
match_pointsArchivePoint 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.
id
How the tools behave.
Your plan decides the tools
A tool above your plan answers with upgrade_required and the plan that has it. Free key: 6 tools. Archive: 31 tools. Odds: 36 tools. Live: 37 tools. See the plans.
One allowance with the API
A tool call counts as one API call, against the same daily and per-minute limits as your key's other calls.
Ids come from search
Players start pl_, tournaments tr_ and venues vn_. The search tool finds any of them by name, on every plan.
Read-only, and logged briefly
No tool changes anything. Each call is logged with the tool, the result and your client's name for 30 days, to help fix problems.