// Handball API mcp server

The MCP server is at https://handballapi.com/mcp (JSON-RPC 2.0 over HTTP POST). Send your key as Authorization: Bearer YOUR_KEY; each tool call is an API call on your plan, with the same limits.

For Claude Code:

claude mcp add --transport http handballapi https://handballapi.com/mcp --header "Authorization: Bearer YOUR_KEY"

The tools:

• yesterdays_results: Every match finished yesterday (UTC), newest first.
• latest_results: Matches finished in the last days, newest first. Results only: served after full time.
• results_on_day: Every match finished on one day (UTC). The free key reaches yesterday and today.
• get_match: Score, half-time, date, venue, crowd, referees and shootout of one finished match.
• match_players: A line for every player listed for the match: goals, shots, 7m, assists, cards, and saves and shots faced for goalkeepers.
• fixtures: Matches scheduled in the coming days, soonest first, with throw-off in UTC and in the league's own time.
• league_table: The table of a competition and season, computed from the results held: played, won, drawn, lost, goals and points.
• top_scorers: The leading scorers of a competition and season, from the player lines held, with matches, 7m goals and goals a match.
• head_to_head: Every finished match between two teams, newest first, with a summary from the first team's side: won, drawn, lost and goals.
• coverage: What the archive holds, counted from the data: matches, results and player lines by country, and what is never collected.
• search_matches: Matches by team, competition, season and dates, finished or scheduled. Give at least one of team, competition, season or from.
• match_officials: The referees of one finished match, each with our referee id where the name is known to us.
• find_competitions: Every competition with results, with country, men or women, league or cup, seasons and dates held.
• competition_seasons: Every season held for a competition, newest first: matches, teams, dates and how many matches have player lines.
• top_goalkeepers: The best save rates of a competition and season, among goalkeepers who faced at least min_shots shots.
• home_away_table: Two tables for a competition and season: home matches only and away matches only.
• league_form: Every team of a competition and season with its last five results and its current run.
• season_stats: A competition season in figures: goals a match, home and away goals, home win, draw and away win rates, average crowd.
• find_teams: Teams by part of the name or by country, with matches held and dates.
• team_results: Every result of a team, newest first, in every competition held.
• team_fixtures: A team's matches still to be played, soonest first.
• team_squad: Every player with a line for the team in a season, with matches and goals.
• team_stats: A team's season per competition: record, goals, home and away, goals a match, form and current run.
• team_form: A team's last results in every competition, newest first, each marked won, drawn or lost.
• player_leaders: The leading players across every competition held, or one season or country: goals, 7m goals, assists or 2 minute suspensions.
• find_players: Players by part of the name, with matches, goals and their last match.
• player_career: A player's career totals, and per competition, across everything held.
• find_referees: Referees by part of the name or by country, with matches held and dates.
• referee_stats: A referee's record: home win, draw and away win rates, goals a match, and 2 minute suspensions and 7m throws a match where player lines are held.
• home_advantage: Home win, draw and away win rates and home and away goals a match, by country and season.

Every tool with its arguments, the endpoint it calls and the plan it needs: MCP tools.

A refusal (your plan, a limit, a match not found) comes back as a tool result with isError, with the reason in words.