statcast_search
Search and retrieve pitch-level MLB Statcast data within specific date ranges, including pitch types, velocities, spin rates, exit velocities, launch angles, and expected statistics. Filter results by team to analyze baseball performance metrics.
Instructions
Search for pitch-level Statcast data within a date range.
Returns pitch-by-pitch data including pitch type, velocity, spin rate, exit velocity, launch angle, expected stats, and more.
Args: start_date: Start date in YYYY-MM-DD format (e.g. '2024-07-04'). end_date: End date in YYYY-MM-DD format. Defaults to start_date for single-day queries. team: Optional three-letter team abbreviation to filter results (e.g. 'NYY', 'LAD', 'BOS').
Data is available from the 2008 season onward. Tip: keep date ranges to 1-5 days for faster results.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| start_date | Yes | ||
| end_date | No | ||
| team | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/statcast_mcp/server.py:374-407 (handler)The statcast_search function is the MCP tool handler for querying pitch-level Statcast data. It leverages pybaseball's statcast function and processes the results with _trim_pitch_cols and _fmt for presentation.
@mcp.tool() def statcast_search( start_date: str, end_date: str | None = None, team: str | None = None, ) -> str: """Search for pitch-level Statcast data within a date range. Returns pitch-by-pitch data including pitch type, velocity, spin rate, exit velocity, launch angle, expected stats, and more. Args: start_date: Start date in YYYY-MM-DD format (e.g. '2024-07-04'). end_date: End date in YYYY-MM-DD format. Defaults to start_date for single-day queries. team: Optional three-letter team abbreviation to filter results (e.g. 'NYY', 'LAD', 'BOS'). Data is available from the 2008 season onward. Tip: keep date ranges to 1-5 days for faster results. """ from pybaseball import statcast if end_date is None: end_date = start_date try: data = statcast(start_dt=start_date, end_dt=end_date, team=team) except Exception as e: return f"Error fetching Statcast data: {e}" data = _trim_pitch_cols(data) return _fmt(data, max_rows=100)