esoccer-battle-mcp
An MCP server for asking natural-language questions about Esoccer Battle results and back-testing your own ideas against historical match data.
Query and filter match rows by date, last N days, venue, format, session, turnus, kick-off window, player/team, opponent, and era.
Get player or team head-to-head records: wins/draws/losses, goals, over/under rates, BTTS, venue/session splits, and recent meetings.
Calculate market hit rates for over/under, BTTS, and 1X2, optionally grouped by venue, session, turnus, month, week, or opponent.
Compare a player’s recent form with their previous N matches.
Back-test custom pre-match rules point-in-time, with hit rate, break-even odds, baseline, and grouped stability results.
Export filtered matches to a CSV file for spreadsheet or custom analysis.
Read data notes about eras, schedule changes, venues, and session mappings.
Check database freshness, coverage, errors, and whether a newer server version exists.
The server provides historical data and analysis only; it includes no tips, odds, strategies, or bookmaker data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@esoccer-battle-mcp head to head of Bjela vs Maki in the last 30 days and the over 5.5 rate"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
esoccer-battle-mcp
An MCP server that lets Claude Desktop, Claude Code or Codex answer questions about Esoccer Battle (the EA FC esports league with 8 and 12 minute matches). It keeps a local copy of every result since 2025-11-11 and adds new matches as they finish.
You ask in plain language: a head-to-head, an over rate per venue, whether a rule you came up with would have made money. The assistant looks it up in the data and answers.
There are no tips, strategies, odds or bookmaker data in here. The ideas are yours; the server only shows how they would have done.
Install
You need uv. That is all: on first start uv downloads Python and the server itself.
Claude Desktop
Settings → Developer → Edit Config, then add this to claude_desktop_config.json:
{
"mcpServers": {
"esoccer-battle": {
"command": "uvx",
"args": ["--from", "git+https://github.com/Jhanee01/esoccer-battle-mcp@v1.0.2", "esoccer-battle-mcp"]
}
}
}Restart Claude Desktop. If it says it cannot find uvx, put the full path there instead (where uvx on
Windows, which uvx on macOS shows it).
Claude Code
claude mcp add -s user esoccer-battle -- uvx --from git+https://github.com/Jhanee01/esoccer-battle-mcp@v1.0.2 esoccer-battle-mcpCodex
Add this to ~/.codex/config.toml:
[mcp_servers.esoccer-battle]
command = "uvx"
args = ["--from", "git+https://github.com/Jhanee01/esoccer-battle-mcp@v1.0.2", "esoccer-battle-mcp"]
required = trueWith required = true Codex waits the few seconds the server needs to start, so the tools are also
there in codex exec runs. If Codex says your model is not supported, pick another one with /model.
Related MCP server: cartola-mcp
First start
The server downloads a ready-made data snapshot (about 12 MB, a few seconds), then fetches the days since the snapshot from the Battle API in the background. That takes a minute or two.
If the snapshot cannot be downloaded (no access to GitHub, a firewall), the server fetches the whole history from the API instead. That runs in the background for 4 to 5 hours. The newest days come first, so you can start asking questions right away.
Tools never wait for a download. Every answer says how far back the data goes and whether it is up to date.
The data is stored in ~/.esoccer-battle-mcp/battle.db. You can run several clients at once: one of
them collects, the others read the same database.
Example questions
"Head to head of Bjela vs Maki in the last 30 days. What is the over 5.5 rate?"
"Which Stamford Bridge turnus has the highest average goals this month?"
"Over 7.5 hit rate per venue and session since the October schedule change."
"Test this rule: both players averaged over 3 goals scored in their last 10 matches and their previous meetings averaged over 7 goals. Bet over 6.5, results per month. What odds would I need?"
"Is Ganger_29 in form? Compare their last 20 matches with the 20 before."
"Export every San Siro match from last week to CSV."

How it works
flowchart LR
API[Battle public JSON API] --> C[collector<br/>live sync + backfill]
S[(GitHub release<br/>data snapshot)] --> C
C --> DB[(SQLite<br/>~/.esoccer-battle-mcp/battle.db)]
M[schedule + eras<br/>menetrend.json, eras.json] --> Q
DB --> Q[stats / test_rule]
Q --> MCP[MCP server<br/>9 tools]
MCP --> CL[Claude Desktop · Claude Code · Codex]Every five days a GitHub Actions workflow (snapshot.yml) syncs the database, builds a
compressed snapshot and publishes it to the data-latest release. A new install is ready in
seconds instead of hours.
Design decisions
Back-tests can't see the future.
test_rulebuilds each match's features only from matches that finished before its kick-off. A rule gets scored on what it could have known at the time.Tools don't wait for data. Collection runs in the background, and every answer says how far back the data goes and whether it's stale. A slow API never holds up a question.
Snapshot first, API second. On first start the server downloads a ~12 MB snapshot and fetches only the days it's missing. If the snapshot can't be reached, it backfills everything from the API, newest days first, so you can start asking within minutes.
One collector, many readers. Several clients can share the same SQLite file at once. A short-lived lease in the database decides which one collects; the others only read, and one of them takes over if the collector stops.
The schedule is data. Sessions and turnus come from a block schedule versioned in the repo, not from the clock. When the league changes its schedule, a release updates the classification instead of matches quietly landing in the wrong session.
No tips included. The server ships without tips, odds or strategies. It tells you how an idea would have done; the idea is yours.
Tools
Tool | What it answers |
| Two players' meetings: record, goals, O/U, BTTS, last results |
| The same for two teams |
| Hit rate of an O/U, BTTS or 1X2 outcome, optionally grouped (venue, session, turnus, month, …) |
| A player's last N matches compared with the N before them |
| The raw match list with filters (up to 500 rows) |
| Back-test of your own rule: hit rate, break-even odds, baseline, results by group |
| Writes the filtered matches to a CSV file you can open in Excel |
| Eras, schedule changes, venues, block times. Worth reading before you look at long periods |
| How fresh the data is, what it covers, recent errors, and whether a newer version is out |
All query tools take the same filters: dates or last_days, venue, format (8min / 12min), session
(day / afternoon / night), turnus (block of the day), kick-off time window and era.
test_rule computes each match's features only from matches played before that kick-off. The
result is what the rule would really have done at the time, not what it looks like with hindsight.
Updating
When a new version is out, sync_status shows it with the release notes, and every answer carries a
short note about it. To update, change the version in your client config (for example @v1.0.2 →
@v1.1.0) and restart the client. Your local data stays.
Updates also bring schedule and era changes: new leagues, new block times, a new game version. Without them, matches after such a change can end up in the wrong session or turnus, so update when you are told to.
Settings
Environment variable | Effect |
| Use this database path instead of |
| Do not collect; only answer from the existing database |
| Never download the snapshot; fetch everything from the API |
| Do not check GitHub for new versions |
Data source and limits
Results come from the public JSON API behind football.esportsbattle.com. This project has nothing to do with Esports Battle. The API is unofficial and may change or go away.
Collected venues: Stamford Bridge, Old Trafford, Wembley, San Siro, Bernabeu (8 min) and Anfield, Etihad (12 min). Not collected: Hillsborough, and Emirates Stadium (a weekend-only "World Cup B" special event with 2-match tournaments, from 2026-06-19 to 2026-07-26).
Session and turnus come from a block schedule maintained in this repo (
src/esoccer_battle_mcp/data/menetrend.json), not from the clock. When the Battle changes its schedule, the next release fixes the classification.Past results do not guarantee future ones. Bet responsibly, and only where it is legal for you.
License
MIT, see LICENSE.
Available Tools
9 toolsdata_notesData NotesARead-only
Context needed to interpret the data: eras (game versions), dated events (schedule changes, new leagues, fixed player-team periods), venues with format and current block schedule, and the turnus -> session map. Read this before analysing windows longer than a few days.
Inputs: venue. Returns: object
export_matchesExport MatchesA
Write every match matching the filters to a CSV file on the user's computer (no row limit), oldest first, for analysis with the user's own code or a spreadsheet. Never overwrites a file.
Inputs: era, path, team, since, +10 more. Returns: object
market_statsMarket StatsARead-only
Hit rates of a market (over/under a line, both teams to score, 1X2) for a player, a pair, a team, or simply everything matching the filters (e.g. a whole venue or turnus), optionally split by venue, session, turnus, month, week or opponent. Without a subject 'home' means player1.
Inputs: market (required), era, line, team, +13 more. Returns: object
player_formPlayer FormBRead-only
Recent form of a player: the last N matches (W/D/L, goals scored/conceded, total goals, BTTS) compared with the N matches before them, plus the last N match rows.
Inputs: player (required), era, since, until, +8 more. Returns: object
player_h2hPlayer H2HBRead-only
Head-to-head record of two players against each other: wins/draws/losses, goal averages, over/under rate per line, both-teams-to-score, split by venue and session, last 10 meetings.
Inputs: player_a (required), player_b (required), era, since, +9 more. Returns: object
query_matchesQuery MatchesARead-only
Raw match rows. Use when the other tools do not answer the question directly; for aggregates prefer player_h2h, team_h2h, market_stats or player_form.
Inputs: era, team, limit, order, +11 more. Returns: object
sync_statusSync StatusARead-only
State of the local database: freshness, coverage, unknown venues, unmatched blocks and the last error. Use when data freshness is in doubt or a response was marked stale.
Inputs: no named parameters. Returns: object
team_h2hTeam H2HARead-only
Head-to-head record of two teams regardless of who controlled them (player names are shown in last_matches). Same statistics as player_h2h. Note: in some leagues players are bound to teams for a period (see data_notes), then team stats effectively measure the player.
Inputs: team_a (required), team_b (required), era, since, +9 more. Returns: object
test_ruleTest RuleARead-only
Back-test the user's own rule on all data, point-in-time: for every match that passes the filters, features are computed ONLY from matches played before it, then the conditions decide if the rule fires and the market outcome is checked. Returns hit rate, break-even odds (1 / hit rate) and a baseline (the same market without the conditions) plus a split for stability. There are no odds in the data: tell the user to compare break_even_odds with their bookmaker's odds, and flag samples under ~50 as unreliable.
Inputs: pick (required), market (required), conditions (required), era, +14 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
The analytical views (player_h2h, team_h2h, market_stats, player_form) all compute hit rates over overlapping subsets, so boundaries are not perfectly crisp, but descriptions differentiate them by subject (player vs team), by comparison (recent N vs prior N), and by split dimensions. query_matches and export_matches are explicitly framed as fallback/raw outlets, and query_matches' description actively redirects to the aggregate tools, which prevents misselection.
All names are snake_case with a clear split between action verbs (query_matches, export_matches, test_rule) and analysis/entity nouns (player_h2h, team_h2h, market_stats, player_form, data_notes, sync_status). The pattern is predictable, with only the verb-vs-noun mix as a minor deviation since it usefully mirrors operation vs dataset.
Nine tools is well within the ideal range and each one earns its place: raw access, bulk export, two h2h dimensions, market hit rates, form, backtesting, plus data context and freshness. No obvious redundancy or filler tools.
The surface covers the full analysis lifecycle from raw rows and CSV export through aggregates, backtesting, and data-context/freshness diagnostics, which is strong for a read-only analytics server. The notable gap is discovery: there is no tool to list or search players, teams, leagues, or venues, so an agent must infer exact names/IDs via query_matches or data_notes.
Maintenance
Related MCP Connectors
Sportsbook and prediction-market prices in Claude and ChatGPT. Needs BeatVig Premium + MCP Access.
Football fixtures, standings, and odds intelligence for AI agents.
Query professional padel tournament data, player stats, and live match results
Grounded sports predictions plus European soccer and tennis arbitrage data for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables querying FIFA World Cup player and team statistics for 2010, 2014, 2018, and 2022 through natural language, providing tools for top scorers, player comparisons, team summaries, and more via a Claude-powered CLI.-
- FlicenseNot gradedqualityDmaintenanceConnects Claude to Cartola FC, enabling queries about matches, player scores, and market information through natural language.-
- AlicenseAqualityCmaintenanceEnables Claude to access live Premier League data—teams, matches, standings, rosters, player details, and schedule-strength analytics—through natural language.12MIT
- AlicenseAqualityCmaintenanceEnables AI assistants to query live football data, including fixtures, live scores, standings, statistics, betting odds, and full odds movement history for corner and card lines.1131 npmMIT