{"id":30868792,"url":"https://github.com/etweisberg/mlb-mcp","last_synced_at":"2026-04-04T17:46:48.979Z","repository":{"id":287788080,"uuid":"963061447","full_name":"etweisberg/mlb-mcp","owner":"etweisberg","description":"MCP server for advanced baseball analytics (statcast, fangraphs, baseball reference, mlb stats API) with client demo ","archived":false,"fork":false,"pushed_at":"2026-03-22T20:30:07.000Z","size":409,"stargazers_count":18,"open_issues_count":1,"forks_count":7,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-23T12:23:44.632Z","etag":null,"topics":["baseball-analytics","baseball-data","baseball-statistics","fangraphs","mcp","mcp-client","mcp-server","mlb-stats-api","statcast"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/etweisberg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-04-09T05:15:58.000Z","updated_at":"2026-03-22T20:30:11.000Z","dependencies_parsed_at":"2025-04-13T23:34:29.404Z","dependency_job_id":"7d332f56-0fff-4f5c-bc54-5c9b95bb0a5c","html_url":"https://github.com/etweisberg/mlb-mcp","commit_stats":null,"previous_names":["etweisberg/mcp-baseball-stats","etweisberg/mlb-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/etweisberg/mlb-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etweisberg%2Fmlb-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etweisberg%2Fmlb-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etweisberg%2Fmlb-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etweisberg%2Fmlb-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/etweisberg","download_url":"https://codeload.github.com/etweisberg/mlb-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/etweisberg%2Fmlb-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31407652,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T10:20:44.708Z","status":"ssl_error","status_checked_at":"2026-04-04T10:20:06.846Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["baseball-analytics","baseball-data","baseball-statistics","fangraphs","mcp","mcp-client","mcp-server","mlb-stats-api","statcast"],"created_at":"2025-09-07T22:03:54.702Z","updated_at":"2026-04-04T17:46:48.938Z","avatar_url":"https://github.com/etweisberg.png","language":"Python","funding_links":[],"categories":["AI/ML"],"sub_categories":[],"readme":"# MLB Stats MCP Server\n\n[![Tests](https://github.com/etweisberg/mcp-baseball-stats/actions/workflows/test.yml/badge.svg)](https://github.com/etweisberg/baseball/mcp-baseball-stats/workflows/test.yml)\n[![Pre-commit](https://github.com/etweisberg/mcp-baseball-stats/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/etweisberg/mcp-baseball-stats/actions/workflows/pre-commit.yml)\n[![smithery badge](https://smithery.ai/badge/@etweisberg/mlb-mcp)](https://smithery.ai/server/@etweisberg/mlb-mcp)\n\nA Python project that creates a Model Context Protocol (MCP) server for accessing MLB statistics data through the MLB Stats API and `pybaseball` library for statcast, fangraphs, and baseball reference statistics. This server provides structured API access to baseball statistics that can be used with MCP-compatible clients.\n\n## Project Structure\n\n- `mlb_stats_mcp/` - Main package directory\n  - `server.py` - Core MCP server implementation\n  - `tools/` - MCP tool implementations\n    - `mlb_statsapi_tools.py` - MLB StatsAPI tool definitions\n    - `statcast_tools.py` - Statcast data tool definitions\n    - `pybaseball_plotting_tools.py` - Additional `pybaseball` tools provided for generating matplotlib plots and returning base64 encoded images\n    - `pybaseball_supp_tools.py` - Supplemental `pybaseball` functions for interfacing with fangraphs, baseball reference, and other data sources\n  - `utils/` - Utility modules\n    - `logging_config.py` - Logging configuration\n    - `images.py` - functions related to handling plot images\n  - `tests/` - Test suite for verifying server functionality\n- `pyproject.toml` - Project configuration and dependencies\n- `.pre-commit-config.yaml` - Pre-commit hooks configuration\n- `.github/` - GitHub Actions workflows\n\n## Tools\n\n## Setup\n\n1. Install uv if you haven't already:\n\n```bash\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n```\n\n2. Create and activate a virtual environment:\n\n```bash\nuv venv\nsource .venv/bin/activate  # On Unix/macOS\n# or\n.venv\\Scripts\\activate  # On Windows\n```\n\n3. Install dependencies:\n\n```bash\nuv pip install -e .\n```\n\n### Installing via Smithery\n\nTo install MLB Stats Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@etweisberg/mlb-mcp):\n\n```bash\nnpx -y @smithery/cli install @etweisberg/mlb-mcp --client claude\n```\n\n### Running Tests\n\nThe project includes comprehensive pytest tests for the MCP server functionality:\n\n```bash\nuv run pytest -v\n```\n\nTests verify all MLB StatsAPI tools work correctly with the MCP protocol, establishing connections, making API calls, and processing responses.\n\n## Environment Variables\n\nThe project uses environment variables stored in `.env` to configure settings.\n\nUse `ANTHROPIC_API_KEY` to enable MCP Server.\n\n### Logging Configuration\n\nThe MLB Stats MCP Server supports configurable logging via environment variables:\n\n- `MLB_STATS_LOG_LEVEL` - Sets the logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)\n- `MLB_STATS_LOG_FILE` - Path to log file (if not set, logs to stdout)\n\n## Claude Desktop Integration\n\nTo connect this MCP server to Claude Desktop, add a configuration to your `claude_desktop_config.json` file. Here's a template configuration:\n\n```json\n\"mcp-baseball-stats\": {\n  \"command\": \"{PATH_TO_UV}\",\n  \"args\": [\n    \"--directory\",\n    \"{PROJECT_DIRECTORY}\",\n    \"run\",\n    \"python\",\n    \"-m\",\n    \"mlb_stats_mcp.server\"\n  ],\n  \"env\": {\n    \"MLB_STATS_LOG_FILE\": \"{LOG_FILE_PATH}\",\n    \"MLB_STATS_LOG_LEVEL\": \"DEBUG\"\n  }\n}\n```\n\nReplace the following placeholders:\n\n- `{PATH_TO_UV}`: Path to your uv installation (e.g., `~/.local/bin/uv`)\n- `{PROJECT_DIRECTORY}`: Path to your project directory\n- `{LOG_FILE_PATH}`: Path where you want to store the log file\n\n## Technologies Used\n\n- `mcp[cli]` - Machine-Learning Chat Protocol for tool definition\n- `mlb-statsapi` - Python wrapper for the MLB Stats API\n- `httpx` - HTTP client for making API requests\n- `pytest` and `pytest-asyncio` - Test frameworks\n- `uv` - Fast Python package manager and installer\n\n## Linting\n\nThis project uses [Ruff](https://github.com/astral-sh/ruff) for linting and code formatting, with pre-commit hooks to ensure code quality.\n\n### Setup Pre-commit Hooks\n\n1. Install pre-commit:\n\n```bash\npip install pre-commit\n```\n\n2. Initialize pre-commit hooks:\n\n```bash\npre-commit install\n```\n\nNow, the linting checks will run automatically whenever you commit code. You can also run them manually:\n\n```bash\npre-commit run --all-files\n```\n\n### Linting Configuration\n\nLinting rules are configured in the `pyproject.toml` file under the `[tool.ruff]` section. The project follows PEP 8 style guidelines with some customizations.\n\n### CI Integration\n\nGitHub Actions workflows automatically run tests, linting, and pre-commit checks on all pull requests and pushes to the main branch.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetweisberg%2Fmlb-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fetweisberg%2Fmlb-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fetweisberg%2Fmlb-mcp/lists"}