All systems normalData updated just nowStatusChangelogSupport
badmintonapi
MCP server

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.

Server address
https://api.badmintonapi.com/mcp
  • Streamable HTTP, JSON-RPC by POST
  • Your key as Authorization: Bearer
  • Every tool is read-only

Connect

1

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.

Get a free key
2

Claude Code

One command, with your key in place of YOUR_KEY.

Terminal
claude mcp add --transport http badminton \
  https://api.badmintonapi.com/mcp \
  --header "Authorization: Bearer YOUR_KEY"
or

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.

MCP settings
{
  "mcpServers": {
    "badminton": {
      "url": "https://api.badmintonapi.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}
Ask it like this

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.

Every tool

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

  • list_countries

    Every country with players held: players, active players, and titles by discipline.

    Free key
  • country_profile

    One country by its IOC code: titles by discipline, its most successful players, recent titles and the editions it hosted.

    code
    Archive

Results and calendar4

  • yesterdays_results

    Every match finished yesterday (UTC), with scores and closing prices.

    Free key
  • results_on_date

    Matches finished on a day. The free key covers yesterday and today; Archive covers every day held.

    datedisciplinepageper_page
    Free key
  • upcoming_matches

    Matches scheduled next and those under way, soonest first.

    disciplinepageper_page
    Free key
  • season_calendar

    A year's tournaments in date order, with dates, city, venue, prize money and whether each is finished, in progress or upcoming.

    yearserieslevel
    Free key

Tournaments and draws5

  • roll_of_honour

    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.

    slugdiscipline
    Archive
  • find_tournaments

    Tournament editions, newest first, with the disciplines and match counts of each.

    seriesyearlevelpageper_page
    Archive
  • tournament_draw

    A whole draw, first round to final, with seeds, scores and closing prices where held.

    iddisciplinesport_class
    Archive
  • team_ties

    A team event (Thomas, Uber, Sudirman Cup): every tie with its nations, score, date and venue, and the matches inside it.

    idstage
    Archive
  • find_matches

    Draw matches by player, tournament, series, year, discipline and round.

    playertournamentseriesyeardisciplineroundwith_oddspageper_page
    Archive

Players10

  • find_player

    Players by name, country (IOC code) and gender, most matches first.

    qcountrygenderpageper_page
    Archive
  • player_matches

    A player's draw matches, newest first.

    idyeardisciplinepageper_page
    Archive
  • player_partners

    A player's doubles partners, most matches together first, with wins and titles as a pair.

    iddiscipline
    Archive
  • player_opponents

    The players met most often, with wins and losses against each and the last meeting.

    iddisciplinelimit
    Archive
  • player_titles

    Every final a player reached, won or lost, newest first, with partner, opponents and score; totals by discipline in meta.

    iddiscipline
    Archive
  • player_form

    A player's latest results, newest first, with the record over them and the winning or losing run they are on.

    iddisciplinelast
    Archive
  • player_stats

    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.

    iddisciplinefromto
    Archive
  • player_schedule

    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.

    iddisciplinedatelast
    Archive
  • player_ranking_history

    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.

    iddiscipline
    Archive
  • head_to_head

    Every meeting of two players, singles or doubles, with the wins of each.

    player1player2
    Archive

Rankings and ratings4

  • world_rankings

    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).

    disciplinedatepageper_page
    Archive
  • world_number_ones

    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.

    disciplinedateplayer
    Archive
  • player_ratings

    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.

    disciplinedateplayeractivepageper_page
    Archive
  • win_chance

    The chance each side wins from our rating, with a fair price and their head-to-head. Singles or doubles, on any date.

    player1player2partner1partner2disciplinedatehostgames
    Odds

Venues and cities2

  • find_venues

    Arenas that have staged tournaments held, most editions first, by country, city or name, with their height above sea level.

    countrycityqpageper_page
    Archive
  • host_cities

    Host cities, most editions first, with their venues and the years they staged tournaments.

    countryqpageper_page
    Archive

Odds and analysis7

  • biggest_upsets

    The biggest upsets: winners at the longest closing prices, or with the lowest chance by our rating.

    bydisciplinefromtolimit
    Odds
  • seed_performance

    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.

    disciplinefromto
    Archive
  • deciding_games

    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.

    bydisciplinefromto
    Archive
  • records

    Records: most titles, most finals, longest winning runs, widest winning margins and most points in a match.

    typedisciplinefromtolimit
    Archive
  • market_accuracy

    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.

    disciplinefromto
    Odds
  • match_odds

    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.

    id
    Odds
  • backtest_strategy

    Run a simple strategy over every settled match with closing prices: strike rate, return and how far it is from chance.

    strategydisciplineroundfromtomin_pricemax_price
    Odds

Live2

  • live_scores

    Matches under way now, with the score so far.

    Live
  • match_points

    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.

    id
    Archive
Good to know

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.