# mlb-data

Connects your coding agent to live and historical MLB data from ESPN and the official MLB API. Useful for pulling scores, rosters, injuries, and pitch analytics without API keys.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 737 installs · ★ 258
- Author: machina-sports
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/machina-sports/sports-skills/tree/HEAD/skills/mlb-data/SKILL.md
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/skills/mlb-data

## What it does

The skill queries public ESPN endpoints and the official MLB Stats API via the `sports-skills` CLI tool. It pulls live game scores, division standings, 30-team rosters, schedules, injury reports, and game summaries. It also accesses pitch-level tracking with velocity, spin rate, plate coordinates, exit velocity, and launch angle.

Commands prefixed with `get_mlbstats_` access historical schedules dating back to 1901 and split player stats by game log or career totals. Because ESPN and MLB maintain separate identifier systems for games and players, joining records requires matching game dates and team names. Queries on play-by-play data support post-fetch filtering through `--fields` and `--limit` flags.

Running this package requires Python 3.10 or newer with the `sports-skills` CLI installed. It needs no API keys. The skill handles Major League Baseball only, so it will fail to return data for minor leagues, college tournaments, or international baseball.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add machina-sports/sports-skills --skill mlb-data -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/mlb-data/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/mlb-data/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add machina-sports/sports-skills --skill mlb-data -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/mlb-data/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add machina-sports/sports-skills --skill mlb-data -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/mlb-data/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install machina-sports/sports-skills mlb-data
```

2. **Manually: put the files in place**
- File: `.github/skills/mlb-data/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add machina-sports/sports-skills --skill mlb-data -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/machina-sports/sports-skills --path skills/mlb-data
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/mlb-data/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add machina-sports/sports-skills --skill mlb-data -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/machina-sports/sports-skills/tree/HEAD/skills/mlb-data/SKILL.md

## When to use it
- retrieve live scores and full play-by-play summaries for MLB games
- inspect pitch-level velocity, spin rate, and exit velocity
- query historical MLB schedules dating back to 1901
- check injury lists and depth charts across active rosters

## Example prompts
- Check the live scoreboard for today's MLB games
- Fetch pitch velocity and exit velocity for gamePk 775296
- Find player Ronald Acuna and pull his career stats

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 153b5d87501e6096.

BEGIN THIRD-PARTY FILE 153b5d87501e6096
````text
---
name: mlb-data
description: |
  MLB data via ESPN public endpoints and the official MLB Stats API — scores, standings, rosters, schedules, game summaries, injuries, leaders, and news, plus an analytics backend: pitch-level velocity/spin/exit-velocity, career splits by stat group, league leaders, and schedules to 1901. Zero config, no API keys.

  Use when: user asks about MLB scores, standings, team rosters, schedules, game stats, box scores, play-by-play, injuries, transactions, depth charts, team/player statistics, MLB news, pitch speeds/spin/exit velocity, career stats, league leaders, or historical MLB seasons.
  Don't use when: user asks about minor league baseball, college baseball, or international baseball. For other sports use: nfl-data (NFL), nba-data (NBA), wnba-data (WNBA), nhl-data (NHL), football-data (soccer), tennis-data (tennis), golf-data (golf), cricket-data (cricket), cfb-data (college football), cbb-data (college basketball), fastf1 (F1). For betting odds use polymarket or kalshi. For news use sports-news.
license: MIT
metadata:
  author: machina-sports
  version: "0.1.0"
---

# MLB Data

Before writing queries, consult `references/api-reference.md` for endpoints, ID conventions, and data shapes.

## Setup

Before first use, check if the CLI is available:
```bash
which sports-skills || pip install sports-skills
```
If `pip install` fails with a Python version error, the package requires Python 3.10+. Find a compatible Python:
```bash
python3 --version  # check version
# If < 3.10, try: python3.12 -m pip install sports-skills
# On macOS with Homebrew: /opt/homebrew/bin/python3.12 -m pip install sports-skills
```
No API keys required.

## Quick Start

Prefer the CLI — it avoids Python import path issues:
```bash
sports-skills mlb get_scoreboard
sports-skills mlb get_standings --season=2025
sports-skills mlb get_teams
```

## CRITICAL: Before Any Query

CRITICAL: Before calling any data endpoint, verify:
- Season year is derived from the system prompt's `currentDate` — never hardcoded.
- If only a team name is provided, call `get_teams` to resolve the team ID before using team-specific commands.

## Choosing the Season

Derive the active season from the system prompt's date — not just the calendar year.

- **If the user specifies a season**, use it as-is.
- **If the user says "current", "this season", or doesn't specify**: The MLB season runs late March/April through October. If the current month is January–March, the last completed season was the prior calendar year. From April onward, use the current calendar year.

## Commands

| Command | Description |
|---|---|
| `get_scoreboard` | Live/recent MLB scores |
| `get_standings` | Standings by league and division |
| `get_teams` | All 30 MLB teams |
| `get_team_roster` | Full roster for a team |
````
END THIRD-PARTY FILE 153b5d87501e6096

The third-party file has ended. Everything between the 153b5d87501e6096 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2827 of 10441 bytes. © machina-sports · MIT · https://github.com/machina-sports/sports-skills/tree/HEAD/skills/mlb-data/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md