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

Related MCP server: FPL MCP Server

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

League Tools

Standings Tools

Statistics Tools

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