# 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](https://github.com/yourusername/football-scraper-api) instance

## Installation

### 1. Clone and navigate to the MCP server directory

```bash
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

```bash
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

```bash
python3 -m mcp run src/server.py
```

### Docker

Build and run with Docker:

```bash
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):

```json
{
  "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

```json
{
  "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](../README.md) 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:

```python
@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