# Statshawk

> Sports stats MCP server and REST API. Normalized data across 50+ competitions in 16 sports, including NBA, MLB, NFL, NHL, and NCAA. Player props, rosters, game logs, MLB play-by-play with Statcast, pregame matchup analysis.

## When to use statshawk

Use statshawk when an agent or product needs **current or historical sports data** for the NBA, MLB, NFL, NHL, NCAA football/basketball, or other tracked competitions, and needs it as structured, normalized JSON rather than scraped HTML. Best-fit jobs:

- Answer "what happened in last night's game": scores, box scores, play-by-play (MLB includes Statcast pitch data).
- Look up a player or team: bio, current roster/membership, season stats, recent game log.
- Build a prop-analysis or matchup memo: `/v1/analysis/player-prop`, `/v1/analysis/compare-teams`, pitcher-vs-batter splits via `/v1/contests/{id}/matchup`.
- Pull standings, schedules, and results for any season of any tracked competition.
- Pull pregame odds: `/v1/contests/{id}/odds` or `/v1/persons/{id}/odds` (spot board 5×), `/v1/contests/{id}/odds/markets` (discovery 1×), `/v1/contests/{id}/odds/history` or `/v1/persons/{id}/odds/history` (10× per page). History paging fields are on `data` (`truncated`, `next_cursor`, `next_before`), not `meta`; prefer `cursor=data.next_cursor`. MCP: `get_odds_markets`, `get_odds_spot`, `get_odds_history` (contest always required; optional `person_id`; prefer `cursor=next_cursor`; MCP limit max 50).
- Power a product feature (sports widget, betting research tool, fantasy assistant, chatbot) that must stay correct as games happen.

How to call it:

- **From an AI assistant (Claude, ChatGPT, Cursor, any MCP client):** connect the Streamable HTTP MCP server at `https://mcp.statshawk.ai/mcp` (OAuth 2.1 + PKCE, scopes `stats:read` and `analysis:read`, all read-only). Server card: https://statshawk.ai/.well-known/mcp/server-card.json
- **From code:** `GET https://api.statshawk.ai/v1/...` with header `X-API-Key: sk_live_...` (or `Authorization: Bearer sk_live_...`). Free key at https://statshawk.ai/signup (no card). OpenAPI 3.1: https://statshawk.ai/openapi.json
- **From a coding agent setting up a project:** `npx -y statshawk-cli@latest init --all --browser` installs the skills and completes browser API-key auth.
- **For a quick read of a public page:** request any stats page with `Accept: text/markdown` or append `.md` to its URL.

Do **not** use statshawk for in-play/live betting prices (pregame boards and paged history are on `/v1/.../odds`; discovery 1× · spot board 5× · history page 10×), for sports it does not track (check `GET /v1/competitions`), or for write operations: the API is read-only.

## Agent onboarding (start here)

- [Agent onboarding skill](https://statshawk.ai/agent-onboarding/SKILL.md): Install, choose Path A–F (MCP / build / workflows / auth / REST / fallback).
- [Auth for agents](https://statshawk.ai/agent-onboarding/auth.md): MCP OAuth and CLI PKCE API-key handoff.
- [MCP skill](https://statshawk.ai/agent-onboarding/mcp/SKILL.md): Live tool routing in-session.
- [Build skill](https://statshawk.ai/agent-onboarding/build/SKILL.md): Wire REST into product code.
- [Workflow skills](https://statshawk.ai/agent-onboarding/workflows/SKILL.md): Prop slate, matchup memo, standings digest.

## Getting started

- [Quickstart](https://statshawk.ai/docs/getting-started/quickstart.md): First request in 60 seconds.
- [Authentication](https://statshawk.ai/docs/getting-started/auth.md): API key format and headers.
- [Errors](https://statshawk.ai/docs/getting-started/errors.md): Error response shape and retry guidance.

## MCP

- [MCP quickstart](https://statshawk.ai/docs/mcp/quickstart.md): Connect from Claude Code in one command.
- [Tool catalog](https://statshawk.ai/docs/mcp/tool-catalog.md): The MCP tools statshawk exposes.

## REST API

- [OpenAPI 3.1 description](https://statshawk.ai/openapi.json): Every `/v1` endpoint, parameter, response schema, typed `ErrorResponse`, and the `X-RateLimit-*` headers. Mirror: https://api.statshawk.ai/api-docs/openapi.json
- [RFC 9727 API catalog](https://statshawk.ai/.well-known/api-catalog): Machine-readable pointers to the REST and MCP surfaces.
- [Endpoint reference](https://statshawk.ai/docs/api): Browsable docs generated from the spec.
- [Versioning & deprecation policy](https://statshawk.ai/docs/getting-started/versioning.md): URL path versioning (`/v1`), additive-only changes within a major except documented changelog exceptions (2026-09-11 quota hard-stop under `/v1`), `Deprecation`/`Sunset` headers and a 90-day minimum notice.
- [Permissions & scopes](https://statshawk.ai/docs/getting-started/permissions.md): Keys are read-only; `sk_live_` vs `sk_test_` environments; MCP OAuth scopes `stats:read` and `analysis:read`.
- [Rate limits](https://statshawk.ai/docs/getting-started/rate-limits.md): Per-second GCRA limiter per account; `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` on every metered response; `Retry-After` on `429`.
- [Quotas](https://statshawk.ai/docs/getting-started/quotas.md): Monthly units and the `X-Account-Quota-*` headers.
- [Error codes](https://statshawk.ai/docs/getting-started/error-codes.md): Machine-readable `error.code` catalog. Every error is `{"error": {"code": "SNAKE_CASE", "message": "..."}}` with an `X-Request-Id` header.

## CLI

- [statshawk-cli on npm](https://www.npmjs.com/package/statshawk-cli): Official CLI (`npm install -g statshawk-cli`, binary `statshawk`). `npx -y statshawk-cli@latest init --all --browser` installs the MCP/build/workflow skills into `.claude/skills`, `.agents`, or `.cursor`, prints the MCP connect command, and runs the browser PKCE flow that writes `STATSHAWK_API_KEY` to `.env`. Source: https://github.com/EdgeHawk-AI/stats-hawk/tree/main/packages/statshawk-cli

## MCP server

- [Server card](https://statshawk.ai/.well-known/mcp/server-card.json) / [Registry manifest](https://statshawk.ai/server.json): Streamable HTTP at `https://mcp.statshawk.ai/mcp`.
- Listed on [Smithery](https://smithery.ai/servers/statshawk/statshawk) and [Glama](https://glama.ai/mcp/connectors/ai.statshawk/statshawk).

## Company

- [About](https://statshawk.ai/about): statshawk is built and operated by EdgeHawk, LLC.
- [Contact](https://statshawk.ai/contact): support@statshawk.ai for API, billing, MCP tool requests and security disclosures; hello@statshawk.ai for everything else.
- [Pricing](https://statshawk.ai/pricing): Free tier, no card; usage-based paid plans.
- [Privacy](https://statshawk.ai/privacy) · [Terms](https://statshawk.ai/terms) · [Changelog](https://statshawk.ai/docs/changelog.md)

## Guides

- [Building a prop-analysis bot](https://statshawk.ai/docs/guides/prop-analysis-bot.md)
- [Pulling MLB Statcast](https://statshawk.ai/docs/guides/mlb-statcast.md)

## Stats

Live and historical sports stats, rendered as public pages for every competition, team, player, and game statshawk tracks.

- [Showcase](https://statshawk.ai/showcase.md): Interactive examples of what the sports data API can build, across NFL, MLB, NCAA, EPL, and WNBA.
- [Scores](https://statshawk.ai/scores.md): Today's cross-competition scoreboard.
- [NBA](https://statshawk.ai/nba.md), [MLB](https://statshawk.ai/mlb.md), [NFL](https://statshawk.ai/nfl.md), [NHL](https://statshawk.ai/nhl.md): Competition hubs: current-season standings, schedule, teams. Every competition statshawk tracks has one at `https://statshawk.ai/<slug>` (slugs come from `GET /v1/competitions`).

Every stats page (`/scores`, `/<comp>`, `/<comp>/<year>`, `/games/<slug>`, `/teams/<slug>`, `/players/<slug>`) also resolves at the same URL with a `.md` suffix (e.g. `https://statshawk.ai/games/lakers-at-celtics-cst_01h8x....md`), returning a markdown summary (headline stats, not the full boxscore or play-by-play) that ends with the equivalent REST call and the MCP connect URL (`https://mcp.statshawk.ai/mcp`). Use the `.md` twin for quick lookups; use the REST API or MCP for full data.