# GoalGorithm MCP Server
Soccer match predictions using xG data and Poisson distribution, exposed as MCP tools for Claude Desktop/Code.
> **Proven in production** — This prediction model is actively used on [BongdaNET](https://bongdanet66.com), a football analytics platform that combines expert analysis with data science to deliver accurate match predictions. BongdaNET also serves as a comprehensive football data hub — offering odds from top bookmakers, live results, fixtures, and standings for leagues worldwide — providing a smart betting experience for punters and football enthusiasts alike.
## Install
```bash
pip install goalgorithm-mcp
```
Or run directly:
```bash
uvx goalgorithm-mcp
```
## Claude Desktop Config
Add to your Claude Desktop config (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"goalgorithm": {
"command": "goalgorithm-mcp"
}
}
}
```
## Example Usage
Once configured, just ask Claude naturally:
> **You:** "Predict Arsenal vs Chelsea this weekend"
Claude will call the `predict_match` tool and respond with something like:
> **Claude:** Here's the prediction for **Arsenal vs Chelsea** (Premier League):
>
> | Outcome | Probability |
> |---------|-------------|
> | Arsenal Win | 52.4% |
> | Draw | 22.7% |
> | Chelsea Win | 24.9% |
>
> - **Expected Goals:** Arsenal 1.85 — Chelsea 1.23
> - **Over 2.5 Goals:** 58.3% | **Under 2.5:** 41.7%
> - **Both Teams to Score:** Yes 52.1% | No 47.9%
> - **Most Likely Scores:** 1-0 (12.8%), 1-1 (11.2%), 2-1 (10.5%)
>
> Arsenal are clear favorites at home with stronger attacking xG.
Other things you can ask:
- *"Show me the La Liga xG table"* — calls `get_league_table`
- *"Which leagues are available?"* — calls `list_leagues`
- *"Who's more likely to win, Bayern or Dortmund?"* — calls `predict_match`
## Tools
### `predict_match`
Predict soccer match outcome using xG-based Poisson model.
```
predict_match(home_team="Arsenal", away_team="Chelsea", league="EPL")
```
**Returns:** win/draw/loss %, over/under 2.5, BTTS, top 3 scores, expected goals, score matrix.
### `list_leagues`
List all supported soccer leagues with IDs and slugs.
### `get_league_table`
Get all teams in a league with their xG statistics, sorted by attacking strength.
```
get_league_table(league="EPL")
```
## Supported Leagues
| ID | League | Slug |
|----|--------|------|
| 9 | Premier League | EPL |
| 12 | La Liga | LaLiga |
| 11 | Serie A | SerieA |
| 20 | Bundesliga | Bundesliga |
| 13 | Ligue 1 | Ligue1 |
## How It Works
1. Fetches team xG/xGA stats from [Understat.com](https://understat.com)
2. Computes attack/defense strength relative to league average
3. Applies Poisson distribution to calculate goal probabilities
4. Builds 6x6 score matrix for all possible scorelines (0-5 goals each)
5. Derives match outcomes: W/D/L, Over/Under 2.5, BTTS
## Data Source
All data from [Understat.com](https://understat.com) public JSON API. Results cached locally for 12 hours.
## License
GPL v2 or later
