MLB Stats MCP

An MCP server that gives Claude (or any MCP client) live and historical Major League Baseball data: players, season and career stats, schedules, live box scores, standings and league leaders.

It uses the public MLB Stats API (statsapi.mlb.com), so there are no API keys or sign-up.

Ask things like:

• "How did Aaron Judge's 2026 compare to his career averages?"

• "Who's pitching for the Dodgers tonight, and what are their ERAs?"

• "Show me the AL standings and who's leading the wild card."

• "Top 10 home run hitters in the NL this season."

Tools

Team arguments accept "Yankees", "NYY", "New York Yankees" or "147".

Caching and retries

Responses are cached in memory, and each kind of data keeps its own lifetime, so repeated questions don't hit MLB again. A cached call takes about 1 ms, compared with about 1.2 s for a fresh one.

The cache keeps at most 1,000 entries and evicts the least recently used. Errors are never cached. Timeouts, connection errors and HTTP 429 or 5xx responses are retried up to 3 times with exponential backoff and jitter, and a Retry-After header is honored. Other 4xx errors fail right away.

Related MCP server: StatsPlus MCP Server

Install

You need uv. It fetches Python for you.

Claude Code

claude mcp add mlb-stats -- uvx mlb-stats-mcp

Claude Desktop, Cursor, Windsurf, VS Code and others

Add this to the client's MCP config. For Claude Desktop, that's Settings → Developer → Edit Config:

{
  "mcpServers": {
    "mlb-stats": {
      "command": "uvx",
      "args": ["mlb-stats-mcp"]
    }
  }
}

Remote (no install)

If someone hosts the server (see below), clients can connect to the URL directly:

claude mcp add --transport http mlb-stats https://YOUR-HOST/mcp

In Claude.ai, go to Settings → Connectors → Add custom connector and paste the same URL.

Development

git clone https://github.com/prnv-13/mlb-stats-mcp
cd mlb-stats-mcp
uv sync

uv run pytest                                # offline unit tests (MLB API is faked)
uv run scripts/smoke_test.py                 # calls every tool over stdio against the live API
uv run mlb-stats-mcp --transport http        # serves http://127.0.0.1:8000/mcp
npx @modelcontextprotocol/inspector          # GUI for poking at tools
claude mcp add mlb-dev -- uv run --directory "$PWD" mlb-stats-mcp   # use your local copy in Claude Code

Layout:

src/mlb_stats_mcp/
  config.py        every constant: URLs, timeouts, cache TTLs, retry policy, limits
  cli.py           entry point: stdio (default) or --transport http
  server.py        build_server(): server identity, instructions, tool registration
  mlb/             data layer, the only code that talks to MLB
    client.py      MLBClient: caching + retries around HTTP
    cache.py       TTLCache: generic TTL + LRU cache
    endpoints.py   API paths
    errors.py      MLBApiError
  tools/           the MCP tools, one module per area
    teams.py  players.py  leaders.py  games.py  standings.py
    common.py      shared types, annotations, date and season helpers
tests/             offline pytest suite, mirrors src/ (mlb/, tools/)
scripts/smoke_test.py   end-to-end test, works on stdio or an HTTP URL
Dockerfile              for hosting the HTTP version

Requests flow one way: cli → server → tools/* → mlb.MLBClient → statsapi.mlb.com. To add a tool, write an async function in the right tools/ module (type hints and the docstring become its schema), then add it to ALL_TOOLS in tools/__init__.py.

Publishing guide

There are two ways people can use your MCP. You can do both.

1. Publish a package so anyone can run uvx mlb-stats-mcp

1. Create accounts on pypi.org and test.pypi.org, then create an API token on each (Account settings → API tokens).

2. Build:

   uv build            # creates dist/*.whl and dist/*.tar.gz

3. Do a test run on TestPyPI:

   uv publish --publish-url https://test.pypi.org/legacy/ --token pypi-XXXX
   uvx --index-url https://test.pypi.org/simple/ --index-strategy unsafe-best-match mlb-stats-mcp --help

4. Publish for real:

   uv publish --token pypi-XXXX

5. For each new release, bump version in pyproject.toml, run uv build, then uv publish.

To skip handling tokens, set up Trusted Publishing on PyPI and publish from a GitHub Action instead.

2. Host it so people only need a URL

The server runs as a stateless Streamable HTTP server, so any container host works. Examples are Render, Railway, Fly.io and Google Cloud Run (many have free tiers). The Dockerfile reads PORT from the platform.

docker build -t mlb-stats-mcp .
docker run -p 8000:8000 mlb-stats-mcp
# → http://localhost:8000/mcp

On Render or Railway, connect the GitHub repo and pick "Docker". Users then add https://your-app.onrender.com/mcp.

The server needs no auth because it only reads public data. If you open it to the internet, consider putting rate limiting in front of it, and keep in mind that heavy traffic hits MLB's API from your server's IP address.

3. Get listed so people can find it

• Official MCP Registry (registry.modelcontextprotocol.io):

  brew install mcp-publisher
  mcp-publisher init        # generates server.json from this repo
  mcp-publisher login github
  mcp-publisher publish

  The registry checks that you own the PyPI package by looking for the mcp-name: comment near the top of this README.

• Community lists: open a PR to awesome-mcp-servers, and submit to directories such as Smithery, Glama and mcp.so.

Data and terms

The data comes from MLB Advanced Media's Stats API. It's © MLB and is offered for individual, non-commercial, non-bulk use. This project isn't affiliated with MLB. Don't use it to build a paid product or to bulk-scrape the API.

License

MIT