football-scraper-mcp

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: ``bash python3 -m venv venv source venv/bin/activate pip install -e . ``

If you don't have python3-venv, install it first: ``bash sudo apt install python3-venv ``

Option B: System-wide installation

On Debian/Ubuntu systems with externally managed Python: ``bash pip3 install -e . --break-system-packages ``

Or if you have modified your pip configuration: ``bash pip3 install -e . ``

4. Configure environment variables

cp .env.example .env

Edit .env to set your API base URL: ``env API_BASE_URL=http://localhost:3000/api/v1 ``

Usage

Running the server directly

If using virtual environment: ``bash source venv/bin/activate python3 src/server.py ``

Or with the full path: ``bash ./venv/bin/python3 src/server.py ``

If using pipx: ``bash football-scraper-mcp ``

If installed system-wide: ``bash 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