# MLB Roster & Player Stats Exporter (`fetch_cat/mlb-stats-scraper`) Actor

Export official MLB roster player bios and season statistics.

- **URL**: https://apify.com/fetch\_cat/mlb-stats-scraper.md
- **Developed by:** [Hanna Nosova](https://apify.com/fetch_cat) (community)
- **Categories:** Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 player stat records

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## MLB Stats Scraper: Roster & Player Statistics

MLB Stats Scraper exports official public MLB roster bios and season player statistics into clean, analysis-ready records. Build a repeatable MLB stats API workflow for fantasy research, baseball player statistics analysis, editorial research, and roster reporting—without an MLB login.

Each result combines player identity, team and position context, biographical details, the selected season/stat group, the complete available statistics object, and a source link. A single request can cover one team, multiple teams, or a known list of player IDs.

### Who is it for?

- **Fantasy and sports analysts** who need current roster context alongside season statistics.
- **Reporters and researchers** building reproducible baseball player statistics exports.
- **Data teams and developers** that need structured player data in an Apify dataset for downstream workflows.
- **AI agents** that need a bounded, attributable MLB roster or player-stat lookup.

### What you get

One normalized record is exported for each player and requested statistic group. Rows retain the official statistics object and source URL for traceability.

- Player identity: `playerId`, `fullName`, `firstName`, `lastName`, and `nameSlug`
- Roster context: `teamId`, `teamName`, `jerseyNumber`, `rosterStatus`, and position fields
- Player bio: birth details, age, height, weight, batting side, throwing hand, and MLB debut date when supplied
- Statistics: `season`, `statGroup`, and the complete available `stats` object
- Provenance: `sourceUrl`, `sourceTeamId`, and `retrievedAt`

### Input recipe

```json
{
  "mode": "roster",
  "teamIds": [147, 121],
  "season": 2025,
  "statGroups": ["hitting", "pitching", "fielding"],
  "includeStats": true,
  "maxItems": 50
}
```

### Input settings

| Input | Description |
|---|---|
| `mode` | Use `roster` for selected team rosters or `playerStats` for explicit player IDs. |
| `teamIds` | MLB team IDs used by roster mode. For example, `147` is the New York Yankees. |
| `playerIds` | MLB player IDs required by `playerStats` mode. |
| `season` | Season year for official player statistics. |
| `statGroups` | Any combination of `hitting`, `pitching`, and `fielding`. |
| `includeStats` | Set to `false` for roster biographies only. |
| `maxItems` | Global player-record cap. Start low when testing a workflow. |

### Example output

```json
{
  "recordType": "mlbPlayerRosterStat",
  "playerId": 645305,
  "fullName": "Ali Sánchez",
  "teamId": 147,
  "teamName": "New York Yankees",
  "positionAbbreviation": "C",
  "season": 2025,
  "statGroup": "hitting",
  "stats": { "gamesPlayed": 12, "hits": 5, "avg": ".217" },
  "sourceUrl": "https://statsapi.mlb.com/api/v1/teams/147/roster?...",
  "retrievedAt": "2026-08-27T00:00:00.000Z"
}
```

### Output fields

| Field | Description |
|---|---|
| `recordType` | Stable `mlbPlayerRosterStat` record label. |
| `playerId`, `fullName`, `firstName`, `lastName`, `nameSlug` | Official player identity. |
| `teamId`, `teamName`, `jerseyNumber`, `rosterStatus` | Roster assignment and status. |
| `positionCode`, `positionName`, `positionAbbreviation` | Official primary roster position. |
| `birthDate`, `birthCity`, `birthStateProvince`, `birthCountry`, `currentAge`, `height`, `weight` | Public player bio fields when supplied. |
| `batSide`, `pitchHand`, `mlbDebutDate` | Official player profile details. |
| `season`, `statGroup`, `stats` | Requested season, group, and complete official statistic object. |
| `sourceUrl`, `sourceTeamId`, `retrievedAt` | Source provenance and retrieval time. |

### Use cases

#### Build a team roster export

Choose `mode: "roster"`, add one or more `teamIds`, and use a moderate `maxItems` value. Select only the statistic groups your analysis needs to keep the output focused.

#### Look up known players

Choose `mode: "playerStats"` and supply `playerIds`. This works well when a separate workflow already has a shortlist of public MLB player IDs.

#### Create a bio-only roster dataset

Set `includeStats` to `false` to return roster and player biography fields without a requested statistics object.

### Pricing

You are charged once when a run begins and for each exported player-stat record. Rates vary by Apify plan; see the live [Actor Pricing tab](https://apify.com/fetch_cat/mlb-stats-scraper/pricing) for current per-result rates before large exports.

### Tips and limits

- Use a low `maxItems` value to validate input and output before a larger export.
- A player can have one row for each requested statistic group; this keeps hitting, pitching, and fielding values unambiguous.
- The source can omit an optional player biography value or a statistic for a player. Those values are returned as `null`, never guessed.
- This focused version exports roster and player-stat records. It does not export schedules, standings, scores, or game-detail entities.
- Results reflect the selected season and data currently available from the official public source.

### API usage

Use the Actor API with the same JSON input shown above. Results are written to the run's default dataset.

#### Node.js

```javascript
import { ApifyClient } from 'apify-client';
const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('fetch_cat/mlb-stats-scraper').call({
  mode: 'roster', teamIds: [147], season: 2025,
  statGroups: ['hitting'], maxItems: 25,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient
client = ApifyClient("YOUR_APIFY_TOKEN")
run = client.actor("fetch_cat/mlb-stats-scraper").call(run_input={
    "mode": "roster", "teamIds": [147], "season": 2025,
    "statGroups": ["hitting"], "maxItems": 25,
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

#### cURL

```bash
curl "https://api.apify.com/v2/acts/fetch_cat~mlb-stats-scraper/runs?token=$APIFY_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"mode":"roster","teamIds":[147],"season":2025,"statGroups":["hitting"],"maxItems":25}'
```

### MCP and AI agents

Add this Actor to an MCP client to let an agent request a bounded roster or player-stat export.

```bash
claude mcp add apify -- npx -y @apify/mcp-server
```

```json
{
  "mcpServers": {
    "apify": {
      "command": "npx",
      "args": ["-y", "@apify/mcp-server"],
      "env": { "APIFY_TOKEN": "YOUR_APIFY_TOKEN" }
    }
  }
}
```

Use the MCP endpoint `https://mcp.apify.com?tools=fetch_cat/mlb-stats-scraper`. Example prompts:

- “Export up to 25 2025 hitting-stat roster records for MLB team ID 147.”
- “Return 10 2025 pitching-stat records for player IDs 592450 and 543037.”

### FAQ

**What data can I export with MLB Stats Scraper?** Each record includes official player identity, roster assignment, position, public biography fields, requested season/stat group, available statistics, and source provenance.

**Can I run MLB Roster & Player Stats Exporter through an API, schedule, or MCP client?** Yes. Use the API input shown above, schedule the same validated input in Apify, or add the listed MCP endpoint to a compatible client.

**How much does it cost to use MLB Roster & Player Stats Exporter?** Billing is per exported player-stat record plus the one-time run start event. Check the live Pricing tab for your current rate.

**Do I need an MLB account?** No. This Actor exports data available from official public MLB sources.

**Why are there multiple rows for one player?** A row is emitted per requested statistic group so values remain unambiguous.

**What are alternatives for schedules or standings?** This Actor intentionally focuses on rosters and player statistics. Use a workflow with a schedule- or standings-specific data source when those are your primary entity.

### Input recipes

- **Quick roster:** `mode: "roster"`, `teamIds: [147]`, `statGroups: ["hitting"]`, and `maxItems: 25`.
- **Player lookup:** `mode: "playerStats"`, `playerIds: [592450]`, the desired `season`, and the required `statGroups`.
- **Bio-only roster:** `mode: "roster"`, `teamIds: [147]`, `includeStats: false`, and `maxItems: 25`.

### Related Actors

- [Google Search Results](https://apify.com/fetch_cat/google-search-results-scraper)
- [Google Images Scraper](https://apify.com/fetch_cat/google-images-scraper)
- [Google News Scraper](https://apify.com/fetch_cat/google-news-scraper)
- [Google Trends Scraper](https://apify.com/fetch_cat/google-trends-scraper)
- [Google Hotels Scraper](https://apify.com/fetch_cat/google-hotels-scraper)

### Support

Need help with an input or result? Open an issue on this Actor's Apify page and include a reproducible report:

- **Run:** the Apify run ID and URL, for example final validation run [`7DkJbupSs53DcNUdQ`](https://console.apify.com/view/runs/7DkJbupSs53DcNUdQ).
- **Complete input JSON:** paste the full submitted JSON, such as:

```json
{
  "mode": "roster",
  "teamIds": [147],
  "season": 2025,
  "statGroups": ["hitting"],
  "includeStats": true,
  "maxItems": 20
}
```

- **Expected vs. actual:** state the expected record count/field values and paste one actual row or the exact error message. For the example above, expect up to 20 `mlbPlayerRosterStat` rows with `season: 2025`, `statGroup: "hitting"`, and a populated `sourceUrl`; report the returned count and the first row if it differs.
- **Public source:** include the reproducible official source URL, such as `https://statsapi.mlb.com/api/v1/teams/147/roster` for this Yankees request.

Do not include API tokens or other secrets in a support report.

# Actor input Schema

## `mode` (type: `string`):

Roster exports selected team rosters; Player stats exports explicit player IDs.

## `teamIds` (type: `array`):

Roster mode team IDs. 147 is the New York Yankees.

## `playerIds` (type: `array`):

Required in Player stats mode.

## `season` (type: `integer`):

MLB season year for official statistics.

## `statGroups` (type: `array`):

Official player statistic groups to include.

## `includeStats` (type: `boolean`):

Turn off for roster biographies only.

## `maxItems` (type: `integer`):

Global output cap; keep low for a quick export.

## Actor input object example

```json
{
  "mode": "roster",
  "teamIds": [
    147
  ],
  "playerIds": [],
  "season": 2025,
  "statGroups": [
    "hitting",
    "pitching",
    "fielding"
  ],
  "includeStats": true,
  "maxItems": 20
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "teamIds": [
        147
    ],
    "playerIds": [],
    "season": 2025,
    "statGroups": [
        "hitting",
        "pitching",
        "fielding"
    ],
    "includeStats": true,
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("fetch_cat/mlb-stats-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "teamIds": [147],
    "playerIds": [],
    "season": 2025,
    "statGroups": [
        "hitting",
        "pitching",
        "fielding",
    ],
    "includeStats": True,
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("fetch_cat/mlb-stats-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "teamIds": [
    147
  ],
  "playerIds": [],
  "season": 2025,
  "statGroups": [
    "hitting",
    "pitching",
    "fielding"
  ],
  "includeStats": true,
  "maxItems": 20
}' |
apify call fetch_cat/mlb-stats-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,fetch_cat/mlb-stats-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MJvkjogAt3VTFmdkE/builds/52BqVAFgYGFIa7ANs/openapi.json