Football Scraper MCP Server

A Model Context Protocol (MCP) server that provides access to football match data, odds, and standings from the football-scraper-api.

Overview

This MCP server exposes tools for querying football data including:

• Live matches and scores
• Today's and upcoming matches
• Match details and betting odds
• League standings and tables
• Team statistics and head-to-head records
• API health and statistics

Prerequisites

• Python 3.11 or higher
• A running football-scraper-api instance

Installation

1. Clone and navigate to the MCP server directory

cd football-scraper-mcp

2. Install dependencies

Option A: Using virtual environment (recommended)

If you have python3-venv installed:

python3 -m venv venv
source venv/bin/activate
pip install -e .

If you don't have python3-venv, install it first:

sudo apt install python3-venv

Option B: System-wide installation

On Debian/Ubuntu systems with externally managed Python:

pip3 install -e . --break-system-packages

Or if you have modified your pip configuration:

pip3 install -e .

4. Configure environment variables

cp .env.example .env

Edit .env to set your API base URL:

API_BASE_URL=http://localhost:3000/api/v1

Usage

Running the server directly

If using virtual environment:

source venv/bin/activate
python3 src/server.py

Or with the full path:

./venv/bin/python3 src/server.py

If using pipx:

football-scraper-mcp

If installed system-wide:

python3 src/server.py

Running with MCP CLI

python3 -m mcp run src/server.py

Docker

Build and run with Docker:

docker build -t football-scraper-mcp .
docker run -i --rm -e API_BASE_URL=http://host.docker.internal:3000/api/v1 football-scraper-mcp

Available Tools

Match Tools

Tool	Description
get_live_matches	Get all currently live football matches
get_today_matches	Get all matches scheduled for today
get_matches	Get matches with flexible filtering (league, status, date, etc.)
search_matches	Search matches by team name
get_match_by_id	Get detailed information about a specific match
get_match_odds	Get betting odds for a specific match
get_head_to_head	Get historical matches between two teams

League Tools

Tool	Description
get_leagues	Get all supported leagues
get_league_by_id	Get detailed information about a specific league

Standings Tools

Tool	Description
get_standings	Get standings for all leagues
get_league_standings	Get standings for a specific league
get_team_standing	Get standing information for a specific team

Statistics Tools

Tool	Description
get_stats	Get comprehensive statistics about matches in the database
get_health	Get API health status and system information
get_health_stats	Get detailed scraping statistics for the last 24 hours

MCP Configuration

Add this server to your MCP settings (e.g., in Claude Desktop or other MCP clients):

Claude Desktop Configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%/Claude/claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "football-scraper": {
      "command": "/path/to/football-scraper-mcp/venv/bin/python3",
      "args": ["/path/to/football-scraper-mcp/src/server.py"],
      "env": {
        "API_BASE_URL": "http://localhost:3000/api/v1"
      }
    }
  }
}

Using with Docker

{
  "mcpServers": {
    "football-scraper": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_BASE_URL=http://host.docker.internal:3000/api/v1",
        "football-scraper-mcp"
      ]
    }
  }
}

Example Queries

Once configured, you can ask your AI assistant questions like:

• "What football matches are live right now?"
• "Show me today's Premier League matches"
• "Get the standings for La Liga"
• "What are the odds for the Manchester City vs Arsenal match?"
• "Show me the head-to-head history between Real Madrid and Barcelona"
• "Search for matches involving Liverpool"
• "Get all matches from the Champions League"

API Reference

This MCP server connects to the football-scraper-api. See the main API README for detailed endpoint documentation.

Development

Project Structure

football-scraper-mcp/
├── src/
│   └── server.py          # Main MCP server implementation
├── pyproject.toml         # Python dependencies
├── Dockerfile             # Container configuration
├── .env.example           # Environment template
├── .gitignore            # Git ignore rules
└── README.md             # This file

Adding New Tools

To add a new tool, define a new async function with the @mcp.tool() decorator:

@mcp.tool()
async def my_new_tool(param: str) -> str:
    """Description of what this tool does.
    
    Args:
        param: Description of the parameter
    
    Returns:
        Description of the return value
    """
    return await make_api_request("/endpoint", {"param": param})

License

MIT