NBA player props by sportsbook since 2023, plus play-by-play, shot locations and odds. REST and MCP.
MCP Server: io.github.noahowsh/dunkapi
The MCP server “io.github.noahowsh/dunkapi” provides NBA, WNBA, and college basketball data. It covers play-by-play details, shot locations, box scores, and odds. The project supports both REST and MCP interfaces for retrieving this information.
🛠️ Key Features
NBA, WNBA, and college basketball data
Play-by-play
Shot locations
Box scores
Odds
REST and MCP access
🚀 Use Cases
Query basketball game events via play-by-play data
Use to find team ids and abbreviations for a season (default: the latest). Every other tool takes a team as an id or abbreviation. Pass league for the WNBA (wnba) or college (ncaam, ncaaw); default NBA. Costs 1 credit.
Parameters2
season
number | string
optional
Season by the year it ends: 2025 = 2024-25. WNBA: the calendar year.
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Raw schema
{
"type": "object",
"properties": {
"season": {
"description": "Season by the year it ends: 2025 = 2024-25. WNBA: the calendar year.",
"type": [
"number",
"string"
]
},
"league": {
"description": "League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.",
"type": "string",
"enum": [
"nba",
"wnba",
"ncaam",
"ncaaw"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
list_games
Use to list games with scores by season, date, date range or team, newest first. For upcoming games with lines use get_schedule; for one game's box score use get_game. Costs 2 credits.
Parameters10
season
number | string
optional
Season by the year it ends: 2025 = 2024-25.
season_type
string
optional
regular, postseason, play_in or preseason.
team
string
optional
Team id or abbreviation.
date
string
optional
One date, YYYY-MM-DD (US Eastern).
from
string
optional
From date, YYYY-MM-DD.
to
string
optional
To date, YYYY-MM-DD.
status
string
optional
limit
integer
optional
Max games (default 50).
offset
integer
optional
Page offset; use next_offset.
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Use for upcoming games (next 1-30 days, default 7) with the median line across posted sportsbooks: spread, total and moneylines. For every book's line use get_odds. Costs 2 credits.
Parameters3
days
integer
optional
Days ahead (default 7).
team
string
optional
Team id or abbreviation.
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Use for one game in full: score, both teams' box scores, every player's line, each sportsbook's opening and closing line, and the win-probability range. For the play-by-play use get_plays. Costs 5 credits.
Parameters2
game_id
string
required
ESPN game id, from list_games or get_schedule.
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Raw schema
{
"type": "object",
"properties": {
"game_id": {
"type": "string",
"description": "ESPN game id, from list_games or get_schedule."
},
"league": {
"description": "League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.",
"type": "string",
"enum": [
"nba",
"wnba",
"ncaam",
"ncaaw"
]
}
},
"required": [
"game_id"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_standings
Use for a season's regular-season standings computed from every final game: overall, conference, home and away records, points for and against, margin and last 10. Costs 2 credits.
Parameters2
season
number | string
optional
Season by the year it ends (default: the latest).
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Raw schema
{
"type": "object",
"properties": {
"season": {
"description": "Season by the year it ends (default: the latest).",
"type": [
"number",
"string"
]
},
"league": {
"description": "League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.",
"type": "string",
"enum": [
"nba",
"wnba",
"ncaam",
"ncaaw"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_injuries
Use for the injury report: every listed player's status (out, day-to-day), injury and expected return, as captured on the latest day (or the latest on or before date). NBA and WNBA. Costs 2 credits.
Parameters3
team
string
optional
One team (id or abbreviation).
date
string
optional
The report as of this day, YYYY-MM-DD (default: the latest).
league
string
optional
League. Defaults to nba. One of: nba, wnba.
Raw schema
{
"type": "object",
"properties": {
"team": {
"description": "One team (id or abbreviation).",
"type": "string"
},
"date": {
"description": "The report as of this day, YYYY-MM-DD (default: the latest).",
"type": "string"
},
"league": {
"description": "League. Defaults to nba. One of: nba, wnba.",
"type": "string",
"enum": [
"nba",
"wnba"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
search_players
Use to find a player's id by name (partial names work), most recent players first. Pass league for the WNBA (wnba) or college (ncaam, ncaaw); default NBA. Costs 1 credit.
Parameters3
name
string
required
Full or partial name.
limit
integer
optional
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Use for a player's profile, per-season averages and shooting splits (regular season and postseason separately) and last 10 games. For every game use get_player_games. Costs 5 credits.
Parameters2
player_id
string
required
ESPN athlete id, from search_players.
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Use for a season's statistical leaders (per game, shooting percentages with a volume floor, or totals) from every box score. Costs 5 credits.
Parameters6
stat
string
required
Stat to rank by.
season
number | string
optional
Season by the year it ends: 2025 = 2024-25 (default: the latest).
season_type
string
optional
Default regular.
min_games
integer
optional
Minimum games played (default: a quarter of the season).
limit
integer
optional
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Raw schema
{
"type": "object",
"properties": {
"stat": {
"type": "string",
"enum": [
"pts",
"reb",
"ast",
"stl",
"blk",
"tpm",
"min",
"plus_minus",
"fg_pct",
"tp_pct",
"ft_pct",
"ts_pct",
"total_pts"
],
"description": "Stat to rank by."
},
"season": {
"description": "Season by the year it ends: 2025 = 2024-25 (default: the latest).",
"type": [
"number",
"string"
]
},
"season_type": {
"description": "Default regular.",
"type": "string",
"enum": [
"regular",
"postseason",
"play_in",
"preseason"
]
},
"min_games": {
"description": "Minimum games played (default: a quarter of the season).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"limit": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"league": {
"description": "League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.",
"type": "string",
"enum": [
"nba",
"wnba",
"ncaam",
"ncaaw"
]
}
},
"required": [
"stat"
],
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_team_stats
Use for team efficiency for a season: pace, offensive, defensive and net rating per 100 possessions, the four factors (eFG%, turnover %, offensive rebound %, free throw rate) and three-point rate, from every box score. Costs 5 credits.
Parameters4
season
number | string
optional
Season by the year it ends: 2025 = 2024-25 (default: the latest).
season_type
string
optional
team
string
optional
One team (id or abbreviation).
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Raw schema
{
"type": "object",
"properties": {
"season": {
"description": "Season by the year it ends: 2025 = 2024-25 (default: the latest).",
"type": [
"number",
"string"
]
},
"season_type": {
"type": "string",
"enum": [
"regular",
"postseason",
"play_in",
"preseason"
]
},
"team": {
"description": "One team (id or abbreviation).",
"type": "string"
},
"league": {
"description": "League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.",
"type": "string",
"enum": [
"nba",
"wnba",
"ncaam",
"ncaaw"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_plays
Use for play-by-play: every event of a game, or a player's or team's plays across a season, with shot location (feet), zone, our expected points, the score and the home win probability after each play (2018 on). Filter to shots, makes or misses, a zone, a period or clutch time. Pass league for the WNBA (wnba) or college (ncaam, ncaaw); default NBA. Costs 10 credits.
Parameters13
game_id
string
optional
One game: every play in order.
player_id
string
optional
A player's plays (with season).
team
string
optional
A team's plays (id or abbreviation).
season
number | string
optional
Season by the year it ends (default: the latest; ignored with game_id).
season_type
string
optional
shots_only
boolean
optional
Field goal and free throw attempts only.
made
boolean
optional
Only made (true) or missed (false) shots.
zone
string
optional
One shot zone.
period
integer
optional
clutch
boolean
optional
Last 5 minutes of the 4th quarter (college men: 2nd half) or overtime, score within 5.
limit
integer
optional
Max plays (default 200).
offset
integer
optional
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Raw schema
{
"type": "object",
"properties": {
"game_id": {
"description": "One game: every play in order.",
"type": "string"
},
"player_id": {
"description": "A player's plays (with season).",
"type": "string"
},
"team": {
"description": "A team's plays (id or abbreviation).",
"type": "string"
},
"season": {
"description": "Season by the year it ends (default: the latest; ignored with game_id).",
"type": [
"number",
"string"
]
},
"season_type": {
"type": "string",
"enum": [
"regular",
"postseason",
"play_in",
"preseason"
]
},
"shots_only": {
"description": "Field goal and free throw attempts only.",
"type": "boolean"
},
"made": {
"description": "Only made (true) or missed (false) shots.",
"type": "boolean"
},
"zone": {
"description": "One shot zone.",
"type": "string",
"enum": [
"restricted_area",
"paint",
"midrange",
"corner_3",
"above_break_3",
"free_throw"
]
},
"period": {
"type": "integer",
"minimum": 1,
"maximum": 10
},
"clutch": {
"description": "Last 5 minutes of the 4th quarter (college men: 2nd half) or overtime, score within 5.",
"type": "boolean"
},
"limit": {
"description": "Max plays (default 200).",
"type": "integer",
"minimum": 1,
"maximum": 1000
},
"offset": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
},
"league": {
"description": "League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.",
"type": "string",
"enum": [
"nba",
"wnba",
"ncaam",
"ncaaw"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_shot_chart
Use for a shot profile: attempts, makes, percentage, points per shot and expected points per shot in each zone (restricted area, paint, midrange, corner three, above-the-break three, free throws) for a player, a team, a team's opponents or one game. include_shots adds every located shot's x/y and result for drawing a chart. Costs 10 credits.
Parameters8
player_id
string
optional
team
string
optional
Team id or abbreviation.
opponent
boolean
optional
With team: the shots its opponents took (its defence).
game_id
string
optional
season
number | string
optional
Season by the year it ends (default: the latest).
season_type
string
optional
include_shots
boolean
optional
Add each shot's x, y and result (up to 3,000).
league
string
optional
League. Defaults to nba. One of: nba, wnba.
Raw schema
{
"type": "object",
"properties": {
"player_id": {
"type": "string"
},
"team": {
"description": "Team id or abbreviation.",
"type": "string"
},
"opponent": {
"description": "With team: the shots its opponents took (its defence).",
"type": "boolean"
},
"game_id": {
"type": "string"
},
"season": {
"description": "Season by the year it ends (default: the latest).",
"type": [
"number",
"string"
]
},
"season_type": {
"type": "string",
"enum": [
"regular",
"postseason",
"play_in",
"preseason"
]
},
"include_shots": {
"description": "Add each shot's x, y and result (up to 3,000).",
"type": "boolean"
},
"league": {
"description": "League. Defaults to nba. One of: nba, wnba.",
"type": "string",
"enum": [
"nba",
"wnba"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_odds
Use for betting lines: each sportsbook's moneyline, spread and total for a game (opening and closing per book from July 2020 from The Odds API, and from 2023-24 from ESPN; ESPN's final line only before that), with implied probabilities and, for finished games, whether the home side covered and the total went over against the median close. Pass game_id for one game (5 credits) or date for a day's games (10 credits).
Parameters3
game_id
string
optional
One game.
date
string
optional
A day's games, YYYY-MM-DD (US Eastern).
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Use to see how a game's line moved before tip-off: our pre-game snapshots of each sportsbook's moneyline, spread and total (ESPN's once a day, The Odds API's every hour for games in the next two days). Costs 10 credits.
Parameters3
game_id
string
required
Game id.
provider
string
optional
One sportsbook, e.g. DraftKings.
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Use for our team power ratings (Elo from every final game in our data), ranked, as of the end of a season or today. Costs 2 credits.
Parameters2
season
number | string
optional
Season by the year it ends (default: the latest).
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.
Raw schema
{
"type": "object",
"properties": {
"season": {
"description": "Season by the year it ends (default: the latest).",
"type": [
"number",
"string"
]
},
"league": {
"description": "League. Defaults to nba. One of: nba, wnba, ncaam, ncaaw.",
"type": "string",
"enum": [
"nba",
"wnba",
"ncaam",
"ncaaw"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_player_props
Use for player prop lines by sportsbook: over/under on points, rebounds, assists, threes, points + rebounds + assists, blocks and steals, from May 2023 for the NBA and WNBA and the 2023-24 season for men's college basketball (DraftKings, FanDuel, BetMGM, ESPN BET, Pinnacle and others). Pass game_id for every player's props in one game (10 credits), or player_id with from_date (and to_date) for one player across games (10 credits per game returned, up to 100). Returns the closing line by default (the last before the game starts) or the opening line, with each book's over and under prices. Set estimate_only to get the price without being charged.
Parameters9
game_id
string
optional
Game id: every player's props for that game.
player_id
string
optional
Player id (e.g. 3945274) from search_players. With from_date: that player's props across games.
from_date
string
optional
With player_id: first date, YYYY-MM-DD (the game's date).
to_date
string
optional
With player_id: last date (default: no end), YYYY-MM-DD (the game's date).
Bookmaker key, e.g. draftkings, fanduel, pinnacle.
snapshot_type
string
optional
closing (default): the last line before the game starts. opening: the first one captured.
estimate_only
boolean
optional
Return what this call would cost, without charging or running it.
league
string
optional
League. Defaults to nba. One of: nba, wnba, ncaam.
Raw schema
{
"type": "object",
"properties": {
"game_id": {
"description": "Game id: every player's props for that game.",
"type": "string"
},
"player_id": {
"description": "Player id (e.g. 3945274) from search_players. With from_date: that player's props across games.",
"type": "string"
},
"from_date": {
"description": "With player_id: first date, YYYY-MM-DD (the game's date).",
"type": "string"
},
"to_date": {
"description": "With player_id: last date (default: no end), YYYY-MM-DD (the game's date).",
"type": "string"
},
"market": {
"description": "One market: player_points (points), player_rebounds (rebounds), player_assists (assists), player_threes (three-pointers made), player_points_rebounds_assists (points + rebounds + assists), player_blocks (blocks), player_steals (steals)",
"type": "string",
"enum": [
"player_points",
"player_rebounds",
"player_assists",
"player_threes",
"player_points_rebounds_assists",
"player_blocks",
"player_steals"
]
},
"bookmaker": {
"description": "Bookmaker key, e.g. draftkings, fanduel, pinnacle.",
"type": "string"
},
"snapshot_type": {
"description": "closing (default): the last line before the game starts. opening: the first one captured.",
"type": "string",
"enum": [
"opening",
"closing"
]
},
"estimate_only": {
"description": "Return what this call would cost, without charging or running it.",
"type": "boolean"
},
"league": {
"description": "League. Defaults to nba. One of: nba, wnba, ncaam.",
"type": "string",
"enum": [
"nba",
"wnba",
"ncaam"
]
}
},
"$schema": "http://json-schema.org/draft-07/schema#"
}
get_prop_history
Use to see how a player did against his prop line over time: for one market (points, rebounds, assists, threes, points + rebounds + assists, blocks or steals), one row per game with the closing line (the median across books, or one book's), the opening line, the prices, what the player actually recorded from our box scores and the result against the line, plus the over rate. Costs 10 credits for up to 200 games.
The basketball data API. NBA play-by-play with the location of every shot, box scores, win probability, standings, injuries, our own team Elo ratings, sportsbook lines and player prop lines, plus the WNBA and men's and women's Division I college basketball. REST API and MCP server. 500 free credits every month, no card.
You: "What was each sportsbook's closing spread for every Celtics home game in 2023-24?"
Claude: [calls get_odds]
You: "Which players took the most shots at the rim in the 2025 playoffs?"
Claude: [calls get_shot_chart]
You: "How often has Jalen Brunson gone over his points line this season?"
Claude: [calls get_prop_history]
Run it locally (stdio)
Most clients connect to https://mcp.dunkapi.com/mcp directly. For a client that launches a local process instead:
It forwards to the hosted server with your key, so every tool and credit cost is the same.
Skills
skills/ holds 16 free Claude skills that turn Claude into a basketball analyst for the NBA, WNBA and men's and women's college basketball. A skill is a markdown file: when to use it, which DunkAPI tools it calls and what they cost, the method (shot zones and expected points, pace and efficiency, rolling game logs, prop modeling, devigging, backtesting), and examples taken from real API responses.
Or with the skills CLI: npx skills add noahowsh/dunkapi-mcp.
Point Claude at the skills/ folder, connect the MCP server below, and ask a question. Start with the dispatch skill if you are not sure which one applies. Skills also work on your own CSV or JSON files, with no key. Full list: skills/README.md.
Upcoming games with the median line across sportsbooks
get_standings
Standings from every final game: overall, conference, home, away, last 10
get_injuries
The latest injury report: status, injury and expected return (NBA, WNBA)
get_ratings
Our team Elo ratings, ranked
get_game
One game: both box scores, every player's line, each book's line, win probability
get_player
Profile, per-season averages and shooting splits, last 10 games
get_player_games
A player's full game log
get_leaders
Season leaders per game, by percentage or in total
get_team_stats
Pace, offensive, defensive and net rating, and the four factors
get_odds
Every sportsbook's moneyline, spread and total for a game (5) or a day (10), with results against the line
get_plays
Play-by-play with shot locations, zones, expected points and win probability
get_shot_chart
Shot profile by zone for a player, team or defence, with every shot's x/y
get_line_movement
Snapshots of each sportsbook's line before tip-off
get_player_props
Player prop lines by sportsbook, opening and closing
get_prop_history
A player's prop lines against the result, game by game
Leagues: nba (default), wnba, ncaam, ncaaw (pass league to any tool).
Data
NBA games since 2003-04 with play-by-play and shot locations (x/y, zone, expected points, win probability)
The WNBA and men's and women's Division I college basketball through the same tools
Team Elo ratings, standings from every final game, injury report (NBA, WNBA)
Per-sportsbook moneylines, spreads and totals: 4 to 12 books per regular-season NBA game from 2013-14 to 2023-24 (10 to 12 from 2020-21), plus opening and closing lines from The Odds API since July 2020 (a median of 7 books per NBA game in 2020-21 to 2022-23, 8 since); pre-game line snapshots from launch: ESPN's once a day, The Odds API's every hour for games in the next two days
Player prop lines by sportsbook (points, rebounds, assists, threes, points + rebounds + assists, blocks, steals) from May 2023 for the NBA and WNBA and from the 2023-24 season for men's college basketball, with the result against each line (get_player_props, get_prop_history)
Women's college basketball: opening and closing lines from November 2024 (a median of 4 books); no player props
500 free credits every month, no card. Plans: Starter $19/mo (10,000 credits), Pro $49/mo (30,000), Scale $149/mo (125,000). Wallet top-ups from $5, never expire. https://dunkapi.com/pricing
Attribution
Basketball data from public ESPN data; sportsbook lines and player props from ESPN and The Odds API. Ratings are ours. Not affiliated with the NBA, WNBA, NCAA or any team.
License
MIT for the contents of this repository. Data terms as above.
Use with Codex
Add this repo as a Codex plugin marketplace, then install the plugin:
bash
codex plugin marketplace add noahowsh/dunkapi-mcp
Then open the plugin directory in Codex and install dunkapi-skills from the dunkapi marketplace. The plugin bundles the skills in skills/ and the DunkAPI MCP server (https://mcp.dunkapi.com/mcp). Set your key first (free at https://dunkapi.com/signup):
