AI Ball — AI football match analysis

io.github.aiballfootyv0.2.0Updated Oct 4, 2026

Football match outcome probabilities recorded before kick-off, and an open record of results.

VerifiedSTDIODesktop onlyFinanceData & Analytics

Overview

AI-generated overview

Read-only access to AI Ball's pre-kick-off football match probabilities and its open record of results.

What it does
Exposes three read-only tools: list_matches returns one calendar day of fixtures with match_id, kick-off time, league, teams and status; get_match_analysis returns one match's home/draw/away probabilities recorded before kick-off, the most likely outcome, confidence and capture time, plus the score and whether it came in once played; get_open_record returns the whole record or one week, with matches counted, hits, two baselines and counts by confidence band. Names are available in English and Malay, and responses are built from a fixed field list.
When to use it
Useful when you want an assistant to look up recorded football probabilities or check how the model's most likely outcome has actually performed, including comparisons against a favourite baseline and a one-in-three random baseline. It is a record lookup, not a live betting or odds feed.
Requirements
Runs locally over stdio; needs Node.js 18 or later. No account or API key. It calls AI Ball's public record API over the network, so internet access is required. AIBALL_API_BASE can point it at another base URL.
Before you install
All tools are read-only and no credentials are requested. Requests go to AI Ball's public API and carry tool parameters (date, time zone, language) and a User-Agent, not your conversation or files; the provider keeps standard access logs. Probabilities are recorded before kick-off and upcoming matches are locked, while pending matches carry a read that may still change.

Installation

In SourceWeft

  1. Open AI Ball — AI football match analysis in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

AI Ball MCP server

Read-only Model Context Protocol server for AI Ball, AI football match analysis.

It gives an AI assistant two things:

  • Pre-kick-off outcome probabilities. For each match, the model's home / draw / away probabilities as recorded before kick-off.
  • The open record. What happened afterwards: the final score and whether the model's most likely outcome came in. Misses are counted the same way as hits, and nothing is removed after the fact.

No account, no API key. The server only calls AI Ball's public record API.

Tools

ToolWhat it returns
list_matchesOne calendar day: match_id, kick-off time, league, teams and status (upcoming, pending or finished)
get_match_analysisOne match: home / draw / away probabilities recorded before kick-off, the most likely outcome, confidence, when the read was captured, and once played the score and whether it came in
get_open_recordThe whole record, or one week with week_start: matches counted, how many went the model's way, two baselines on the same matches, and the count by confidence band

Every tool is read-only (readOnlyHint: true). Names are available in English (lang: "en") and Malay (lang: "ms"). Responses are built from a fixed list of fields; nothing from the upstream API is passed through as-is.

Reading the numbers

  • models.balanced holds fractions for home, draw and away that sum to 1. This version returns the balanced model; models_available lists what is included.
  • result.hit is true when the model's most likely outcome happened.
  • hit_rate is a percentage. null means the sample is under min_band_sample, so use the counts hits and n instead.
  • favourite_baseline scores the same matches by always taking the pre-match favourite; random_baseline is one outcome in three.
  • upcoming matches are locked before kick-off. pending matches carry a current read that may still change.

The server caches each upstream response for five minutes and spaces its requests, so repeated questions do not hit AI Ball's API again.

Install

Claude Desktop

Download aiball-mcp.mcpb from the latest release and open it.

Claude Code

bash
claude mcp add aiball -- npx -y github:aiballfooty/aiball-mcp

Cursor, VS Code and other clients

json
{  "mcpServers": {    "aiball": {      "command": "npx",      "args": ["-y", "github:aiballfooty/aiball-mcp"]    }  }}

Requires Node.js 18 or later.

Example questions

  • "How did AI Ball's model do on last week's matches?"
  • "Which of last week's matches did the model get wrong?"
  • "What are the model's probabilities for today's matches, in Malaysia time?"
  • "Across the whole record, does the model do better than always taking the favourite?"

Privacy

The server runs on your machine and sends requests only to https://aiball.samagent.ai/api/v1. Requests carry the tool's parameters (a date, a time zone, a language) and a User-Agent of aiball-mcp/<version>. They do not carry your conversation, your files or any identifier. AI Ball's web server keeps standard access logs. Site privacy policy: https://aiball.samagent.ai/en/privacy

Development

bash
npm installnpm test        # starts the server and calls every tool against the live API

Set AIBALL_API_BASE to point the server at another base URL.

Licence

MIT. For information only. Not advice. 18+.

Source: README.md at commit a80d82b

Tools

0
Tool metadata has not been indexed yet.

Version history

1
  1. v0.2.0LatestOct 4, 2026