TKB Picks MCP Server (v2.8.6)

MCP server wrapping SportsGameOdds (odds, schedules, props, results) and BALLDONTLIE (stats, injuries, standings) for building TKB Picks betting threads across MLB, WNBA, NFL, CFB, and ATP/WTA tennis.

Deploy

Render Web Service, Node environment:

• Build: npm install && npm run build

• Start: npm start

• Env vars: SGO_API_KEY, BDL_API_KEY, CFBD_API_KEY, CBBD_API_KEY (the two college keys are optional and SEPARATE from each other, though they share one monthly quota: without either, every other tool works and that sport's hit rates refuse rather than fall back)

• MCP endpoint: https://<your-app>.onrender.com/mcp

• Health check: /health

Then verify rather than assume:

npm test                                        # no network needed
node scripts/verify-deploy.mjs --expect 2.8.6
node scripts/verify-deploy.mjs --screen <mlbEventID>   # measures entity cost

/health returns version, toolCount, tools and sports. The last three are read off a running server, so they cannot go stale independently of the code. If the version looks old but sports contains atp, the build is new and only the constant was forgotten.

Related MCP server: MLB V3 Scores MCP Server

Sports and what each one supports

Capabilities are declared in src/constants.ts and checked by each tool. A sport that does not support something returns an explanation naming the reason, never an empty result that reads like an answer.

Tennis is moneyline only. Competitors occupy the home/away participant slots on an event rather than roster positions, so event.players is permanently empty and player props cannot be addressed by playerID. This is structural, not unfinished. Use tkb_get_odds with marketType="moneyline".

Tools (27)

Picks

Content

Results

Ops

Design rules this connector actually enforces

These are not aspirations. Each one exists because its absence caused a specific published or near-published error, documented in docs/.

• A price is only usable if a named sportsbook posted it. SGO's modelled fairOdds is never returned as odds. Four categories are blocked at the pricing layer so no call site can source from them, kept in separate sets because the REASON decides what to expect: pick'em apps (Underdog, PrizePicks, Sleeper, Betr, Dabble, ParlayPlay) distort by being flat; Fliff is real but unbettable here; prediction markets (Polymarket, Kalshi, PredictIt, Manifold) price contracts that are not comparable to an over/under; and offshore books (BetOnline, Bovada, MyBookie, BetUS and peers, added v2.8.6) post real prices a US follower cannot legally bet.

• The book filter is one constant, imported everywhere. DEFAULT_BOOKMAKERS in src/constants.ts. All six odds tools use it, so changing which books this account prices against is a one-line edit in one file.

• Hit rates are counted, never estimated. Sample size is the real number of appearances, DNPs excluded rather than counted as misses.

• A stat that cannot be resolved returns null, never 0. A missing field reading as zero is indistinguishable from a real zero.

• Ordering is self-describing. Game logs carry dates on every entry, because a bare newest-first array was once read backwards and published as its inverse.

• Warnings, not filters. Stale samples and playing-time risk are surfaced with reasons; the writer decides. A tool that silently drops props teaches nothing.

• Decaying facts come from the connector, never from an article. Records, streaks, standings position and rankings are wrong the moment a team plays again. tkb_get_standings and tkb_get_rankings exist so those numbers are always re-derived rather than quoted from a source with a publish date.

• A missing rate is not a missing market. tkb_screen_props cannot rank what it cannot score, so on a sport with no rate source it returns an empty board while a full one exists. tkb_get_prop_board prints that board. Being unable to grade a market is not a reason to hide that it is priced.

• An unanswerable question gets a refusal, not a plausible answer. This is why capability flags exist, and why an empty injury filter can return CANNOT VERIFY.

Repo layout

src/
  constants.ts        sport config + capability flags (start here)
  types.ts            provider response shapes
  index.ts            server, tool registration, /health
  services/           API clients, aggregators, pricing, catalogs
  tools/              one file per registered MCP tool
  data/               stadiums, CFB tiers
test/                 npm test, no network required
scripts/              verify-deploy.mjs
docs/                 changelogs, one per release
archive/tools/        removed in v2.0.0, kept for reference only

Known gaps

• CFB hit rates need a team NAME, not an SGO teamID. CollegeFootballData keys box scores by name, so tkb_get_player_hit_rate takes an optional teamName and falls back to deriving one from the teamID. Pass it explicitly for CFB. Until v2.8.6 the teamID went through unconverted and every CFB hit rate returned NO SAMPLE.

• CFB availability is never probed. SGO carries no CFB player box scores outside the playoff, so tkb_screen_props skips the playing-time probe for CFB rather than spending ~60 entities a game to return an empty map. Confirm CFB availability from a published depth chart, and run tkb_verify_roster first to catch a stale team field.

• CFB injuries are unavailable through BALLDONTLIE on the current plan.

• WNBA and NCAAF player stats are GOAT-gated on BDL, so their hit rates fall back to SGO. A 401 disables the BDL path for 30 minutes and heals itself, so an upgrade takes effect without a redeploy.

• SGO events carry no lineups field. Confirmed live 2026-08-27 via tkb_probe_event_fields against an upcoming MLB game: the event has 11 top-level keys and lineups is not among them, despite SGO's schema browser listing it. Confirmed starting pitchers still require a live web search, per game, per date.

• Retractable roofs are never assumed. Roof status is a same-day team decision; those stadiums are flagged for manual verification.

• CFB rankings now come from BALLDONTLIE, not a live search. SGO still does not expose a ranking field, but BDL publishes the AP poll on the NCAAF ALL-STAR tier this account already holds. Run tkb_get_rankings and feed its rankedTeams string into tkb_get_schedule.

• Player props appear close to game time. An empty roster means "not priced yet", not "no players". Build threads inside the normal pre-game window.

• SGO carries no CFB player box scores outside the playoff. Measured 2026-08-31: Dante Moore started all 15 of Oregon's 2025 games and had a settled passing line in 3, all playoff games; Maddux Madsen, 1 of 14. CFB hit rates therefore come from CollegeFootballData, and with no CFBD_API_KEY set they REFUSE rather than fall back - an SGO fallback would report started games as DNPs.

• In the opening weeks of any season there is no current-year sample. Pass includePriorSeason: true to widen the lookback to its 400-day ceiling and reach last season, and take it off around Week 5. tkb_get_prop_board and tkb_get_game_lines still work with no rate source at all.

• CFBD lists a player only where he recorded a stat, so absence cannot separate "did not play" from "quiet game". CFB availability returns UNKNOWN rather than a false OK, and depth-chart confirmation stays manual.

• Tennis grading is unconfirmed against live data. The code path exists and needs one finished match to validate. See docs/CHANGES-v2_6_0.md.