jk-mcp-epl

MCP server that gives Claude live access to Premier League data — teams, matches, standings, rosters, richer player data from Pulselive/Opta, and schedule-strength analytics.

Table of Contents

• Overview

• Features

• Requirements

• Installation

• Usage

• Configuration

• Claude Code

• Claude Desktop

• Docker

• Development

• Contributing

• License

Related MCP server: cartola-mcp

Overview

AI assistants like Claude are knowledgeable, but they have a hard cutoff date — they cannot tell you today's Premier League standings, last night's scores, or which teams are fighting for the title, European places, or against relegation. This project fixes that.

It is an MCP server — a plugin that gives Claude direct access to live Premier League data: scores, standings, rosters, derived schedule-strength analytics, and richer per-player registrations from the Pulselive/Opta feed that powers premierleague.com. Once installed, you can ask Claude natural-language questions about the Premier League and get accurate, up-to-date answers. No subscription, no API key, and no programming required to use it.

This is the v1 scaffold: two data sources — ESPN's public API for the normalized league feed, and footballapi.pulselive.com (used unauthenticated, requires an Origin: https://www.premierleague.com header) for Opta-cross-referenced player data. Cup competitions (FA Cup, Carabao Cup) and per-half / xG stats are on the roadmap.

Features

The v1 surface is twelve read-only, idempotent tools split across three tiers.

ESPN-backed (8)

Pulselive-backed (1)

Derived analytics (3)

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

Roadmap

Deferred to v2+:

• FA Cup (eng.fa) and Carabao Cup (eng.league_cup) — ESPN slugs already available

• UEFA competitions (Champions League, Europa) — cross-competition tool surface

• Per-half and home/away split standings from Pulselive

• xG / shots / advanced Opta stats (Pulselive exposes them; needs an LLM-friendly formatter)

• Season lookup by year (currently get_players defaults to the most recent completed season)

Requirements

• Python 3.13+

• uv

Installation

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

Usage

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

uv run python -m epl.server

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

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

Example prompts

Standings, scores, rosters:

• Who is leading the Premier League right now?

• Show me every Premier League result from this past weekend.

• Who is on Arsenal's roster?

• When does Liverpool play next?

• Show me the full Pulselive player registry for Manchester City — who's on loan?

Schedule strength:

• Which Premier League team has played the toughest schedule so far?

• Show me Arsenal's record against the current top 6 teams.

• Compare Manchester City and Liverpool 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 epl -- uv run --directory /path/to/jk-mcp-epl python -m epl.server

Replace /path/to/jk-mcp-epl 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": {
    "epl": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/jk-mcp-epl", "python", "-m", "epl.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": {
    "epl": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/jk-mcp-epl",
        "python", "-m", "epl.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-epl:latest .

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

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

Run in HTTP mode:

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

Development

Install

uv sync

Invoke tasks

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

Project structure

src/epl/
├── 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                # EPLService — use cases, orchestration
│   ├── _helpers.py               # input validation
│   └── _analytics_helpers.py     # pure math for schedule-strength tools
├── domain/
│   ├── models.py                 # Team, Match, Standing, etc.
│   └── exceptions.py             # EPLNotFoundError, UpstreamAPIError
├── ports/
│   ├── inbound.py                # Authorizer protocol
│   └── outbound.py               # EPLAPIPort 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.