Liga MX API

Query Liga MX form, head-to-head history, and tournament standings from football-data.co.uk match data.

Data is rebuilt daily into a local SQLite database (data/ligamx.db). Form and H2H are answered from the matches table; standings are materialised at rebuild time.

Setup

Requires Python 3.12+ and uv.

uv sync
./scripts/rebuild_db.sh   # download MEX.csv + build SQLite

Or rebuild from an existing CSV without re-downloading:

uv run python -m ligamx.etl

Related MCP server: copamind-mcp

Run the server

One process serves both the REST API and MCP (streamable HTTP):

uv run ligamx-serve
# or
uv run uvicorn ligamx.api:app --reload

• REST docs: http://127.0.0.1:8000/docs

• MCP endpoint: http://127.0.0.1:8000/mcp

Deploy on Fly.io

The image rebuilds data/ligamx.db from football-data.co.uk on every start (fits free machines that stop when idle).

# once: install flyctl, log in, then from the repo root:
fly launch        # accept the existing fly.toml; pick a unique app name if needed
fly deploy

Useful checks:

fly status
fly logs
fly open /docs

App URL will look like https://<app-name>.fly.dev — MCP at /mcp, REST docs at /docs.

After deploy, optional daily refresh without idle sleep:

fly machine run --schedule daily ...   # or just rely on rebuild-on-boot when traffic wakes the machine

On the free allowance, auto_stop_machines means the first request after idle pays a cold start (download CSV + ETL + boot).

MCP (HTTP)

Point an MCP client at the streamable HTTP URL (no stdio):

{
  "mcpServers": {
    "ligamx": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Exact client config keys vary; the transport is streamable HTTP at /mcp.

MCP tools

REST and MCP share ligamx/service.py payloads.

Endpoints

Unknown team slugs return 404.

Examples

curl 'http://127.0.0.1:8000/teams/america/form?n=10'
curl 'http://127.0.0.1:8000/h2h/america/guadalajara'
curl 'http://127.0.0.1:8000/standings/current'
curl 'http://127.0.0.1:8000/teams/tigres/position'

Pipeline

MEX.csv  →  ligamx.etl  →  ligamx.db  →  FastAPI (REST + MCP /mcp)
                 │
                 ├─ matches (raw names + slugs)
                 └─ standings (per season + tournament)

1. scripts/rebuild_db.sh downloads https://www.football-data.co.uk/new/MEX.csv (overwrite) and runs the ETL.

2. ETL loads matches via the CSV reader, normalises team names to slugs, writes a temp SQLite file, then atomically replaces data/ligamx.db.

3. Standings are aggregated with 3/1/0 points and ranked by points → goal difference → goals for.

Tournaments

The CSV only has a Season string (e.g. 2025/2026). Short tournaments are derived from the match date:

• Apertura — July–December

• Clausura — January–June

“Current” standings use the season and tournament of the latest match in the database.

Team slugs

Raw CSV labels are kept on each match; API paths use stable slugs from ligamx/teams.py:

Package layout

Library usage

from ligamx.queries import get_form, get_h2h, get_standings, get_position

get_form("america", n=5)
get_h2h("america", "guadalajara")
get_standings()           # current tournament
get_position("tigres")