jk-mcp-mls

MCP server that gives Claude live access to Major League Soccer data — teams, matches, standings, rosters, and schedule-strength analytics — via the ESPN public API.

Table of Contents

• Overview

• Features

• Requirements

• Installation

• Usage

• Configuration

• Claude Code

• Claude Desktop

• Docker

• Development

• Contributing

• License

Related MCP server: ESPN Fantasy Basketball MCP Server

Overview

AI assistants like Claude are knowledgeable, but they have a hard cutoff date — they cannot tell you today's MLS standings, last night's scores, or which teams are currently in a playoff position. This project fixes that.

It is an MCP server — a plugin that gives Claude direct access to live MLS data: scores, standings, rosters, and derived schedule-strength analytics. Once installed, you can ask Claude natural-language questions about Major League Soccer and get accurate, up-to-date answers. No subscription, no API key, and no programming required to use it.

This is the v1 scaffold — it wraps the ESPN public API only. Richer sources (mlssoccer.com's Opta-powered feed, official CMS award articles, Leagues Cup, U.S. Open Cup, Concacaf Champions Cup) are on the roadmap.

Features

The v1 surface is eleven read-only, idempotent tools split across two tiers.

ESPN-backed (8)

Derived analytics (3)

Pure functions over live standings + team schedules, exposing schedule-strength context the raw table does not.

Roadmap

Not in v1; probed and shown to be viable at the ESPN API:

• Leagues Cup (concacaf.leagues.cup), U.S. Open Cup (usa.open), Concacaf Champions Cup, Campeones Cup

• Player leaderboards and team season aggregates once a stable MLS Opta feed is identified

• Award articles via mlssoccer.com CMS

• Playoff bracket for the MLS Cup Playoffs

Requirements

• Python 3.13+

• uv

Installation

git clone https://github.com/jedi-knights/jk-mcp-mls.git
cd jk-mcp-mls
uv sync

Usage

Run the server in stdio mode (the default — used by Claude Code and Claude Desktop):

uv run python -m mls.server

Run in HTTP mode (for networked or deployed access):

MCP_TRANSPORT=streamable-http uv run python -m mls.server

Example prompts

Standings, scores, rosters:

• Who is leading the MLS Eastern Conference right now?

• Show me every MLS result from this past weekend.

• Who is on Atlanta United's roster?

• When does LAFC play next?

Schedule strength:

• Which MLS team has played the toughest schedule so far?

• Show me Atlanta United's record against the current top 5 teams.

• Compare Inter Miami and Seattle Sounders on adjusted points-per-game.

Configuration

All configuration is via environment variables. None are required for local use.

Claude Code

Install from your local clone globally so the server is available in every project:

claude mcp add --scope user mls -- uv run --directory /path/to/jk-mcp-mls python -m mls.server

Replace /path/to/jk-mcp-mls with the absolute path to your clone. Verify with claude mcp list.

Drop --scope user to register only for the current project, or commit a .mcp.json to the repo root for collaborators:

{
  "mcpServers": {
    "mls": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/jk-mcp-mls", "python", "-m", "mls.server"]
    }
  }
}

Claude Desktop

Add the following to your Claude Desktop configuration file.

Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mls": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/jk-mcp-mls",
        "python", "-m", "mls.server"
      ]
    }
  }
}

If uv is not on Claude Desktop's PATH, use the absolute path (which uv will show it). Fully quit and relaunch Claude Desktop after saving — a window close is not enough.

Docker

Build the image:

docker build -t jk-mcp-mls:latest .

Run in stdio mode (for MCP clients that spawn a subprocess):

docker run -i --rm jk-mcp-mls:latest

Run in HTTP mode:

docker run --rm -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  jk-mcp-mls:latest

Development

Install

uv sync

Invoke tasks

All common workflows are invoke tasks. Run uv run inv --list to see everything.

Project structure

src/mls/
├── server.py                     # entry point, transport selection, logging setup
├── adapters/
│   ├── inbound/
│   │   ├── mcp_adapter.py        # FastMCP server, health endpoints, tool registration
│   │   ├── formatters.py         # domain → LLM-readable text
│   │   ├── authorization.py      # inbound authz port implementations
│   │   └── tools/
│   │       ├── espn.py           # 8 ESPN-backed tools
│   │       └── analytics.py      # 3 schedule-strength analytics tools
│   └── outbound/
│       ├── espn_adapter.py       # ESPN HTTP client
│       ├── parsers.py            # ESPN JSON → domain models
│       ├── retry_adapter.py      # transient-failure retry decorator
│       └── caching_adapter.py    # in-process TTL cache
├── application/
│   ├── service.py                # MLSService — use cases, orchestration
│   ├── _helpers.py               # input validation
│   └── _analytics_helpers.py     # pure math for schedule-strength tools
├── domain/
│   ├── models.py                 # Team, Match, Standing (with conference), etc.
│   └── exceptions.py             # MLSNotFoundError, UpstreamAPIError
├── ports/
│   ├── inbound.py                # Authorizer protocol
│   └── outbound.py               # MLSAPIPort protocol
├── observability/                # OpenTelemetry bootstrap (opt-in)
└── security/                     # JWKS token verifier

The dependency direction flows inward: adapters → ports → domain. Nothing in domain/ imports from adapters or a framework.

Contributing

1. Fork the repository and clone your fork

2. Create a feature branch: git checkout -b feature/your-feature

3. Make your changes following the existing patterns (hexagonal architecture, TDD, conventional commits)

4. Verify the full check suite passes: uv run inv lint && uv run inv check-complexity && uv run inv coverage

5. Open a pull request against main

All CI checks (lint, complexity, tests, coverage ≥ 90%) must pass before merge.

License

MIT — see LICENSE.