Football Intelligence MCP

Локальный сервер Model Context Protocol, который даёт любому MCP-хосту — Claude Desktop, Claude Code или собственному чат-боту — доступ к курируемой исторической футбольной базе данных, охватывающей 36 982 матча в семи ведущих европейских соревнованиях с 2010 по 2025 год.

Протокол реализован напрямую поверх JSON-RPC 2.0, без использования какого-либо MCP SDK: каждое сообщение собирается и разбирается вручную в соответствии со спецификацией 2025-06-18.

Что в базе данных

Данные изначально извлечены из API-Football и нормализованы в PostgreSQL.

Известные ограничения покрытия

Сервер сообщает о них вместо того, чтобы гадать, и вам тоже следует так делать:

• Статистика матчей начинается с 2015 года. Сезоны 2010–2014 содержат результаты, голы, события и составы, но без ударов, владения мячом или данных о передачах.

• Ожидаемые голы (xG) существуют только с 2023 года и никогда для Лиги чемпионов.

• Данные о тактической схеме и тренере начинаются с 2015 года.

• У 58 матчей (0.16%) в списке событий отсутствует один гол — пробел на стороне API-Football. Счёт это не затрагивает; он берётся из записи матча, а не суммированием событий.

Вызовите инструмент data_coverage, чтобы проверить, что есть для любой лиги и сезона.

Установка

Требуются Python 3.10+ и PostgreSQL 14+.

git clone https://github.com/jaq23369/football-intelligence-mcp.git
cd football-intelligence-mcp

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

createdb football
pg_restore -d football data/football.dump

cp .env.example .env      # edit DATABASE_URL if your setup differs

Проверьте восстановление:

psql -d football -c "SELECT count(*) FROM fixtures;"
#  count
# -------
#  36982

Запуск сервера

python server.py

Сервер общается по JSON-RPC через stdio. Обычно его запускает MCP-хост, а не вручную, но вы можете управлять им напрямую:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | python server.py

Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "football": {
      "command": "/absolute/path/to/football-intelligence-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/football-intelligence-mcp/server.py"]
    }
  }
}

Claude Code

claude mcp add football -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

Протокол

Транспорт: stdio, JSON с разделителями строк. Версия протокола 2025-06-18.

Ошибки соответствуют JSON-RPC 2.0: -32700 ошибка разбора, -32600 недопустимый запрос, -32601 метод не найден, -32602 недопустимые параметры, -32603 внутренняя ошибка.

Сбои на уровне инструментов — не ошибки JSON-RPC: они возвращают обычный результат с isError: true, чтобы модель могла прочитать сообщение и восстановиться.

stdout несёт только JSON-RPC. Все диагностические сообщения идут в stderr.

Инструменты

search_team

Находит команды по части имени, ранжируя по количеству матчей в базе. Вызовите его первым — каждому другому инструменту для команд нужен team_id.

{"name": "search_team", "arguments": {"query": "Liverpool", "limit": 1}}

[{"team_id": 40, "name": "Liverpool", "country": "England",
  "founded": 1892, "partidos": 762,
  "primera_temporada": 2010, "ultima_temporada": 2025}]

search_player

Находит игроков по имени, ранжируя по сыгранным минутам.

get_match

Полная запись матча: счёт, стадион, судья, статистика по каждой команде и каждый гол с минутой и голевой передачей. Матчи до 2015 года возвращают явное примечание вместо пустой статистики.

get_team_form

Текущая форма: серия, очки, забитые и пропущенные голы.

before ограничивает расчёт матчами, которые строго раньше этой даты, что позволяет восстановить состояние команды в любой прошлый момент. Это защита от смещения заглядывания вперёд при построении прогнозных признаков.

{"name": "get_team_form",
 "arguments": {"team_id": 40, "last": 5, "before": "2020-01-01"}}

get_head_to_head

Баланс побед/ничьих/поражений между двумя командами, их последние встречи и средние показатели по каждой команде (голы за матч, жёлтые/красные карточки, фолы, угловые) за всю историю — полезный контекст для решения о ставке, а не просто число-прогноз. Карточки/фолы/угловые доступны только для матчей с 2015 года; матчи без статистики исключаются из этих средних, а не считаются нулевыми.

get_team_season

Итоговая позиция в лиге, очки и голы, а также средние за матч показатели ударов, владения мячом, угловых и точности передач.

Сезоны называются по стартовому году: 2024 означает сезон 2024-25.

get_player_season

Суммарные показатели игрока за сезон, агрегированные из записей матчей: голы, голевые передачи, минуты, удары, точность передач.

compare_teams

Текущая форма двух команд плюс их очные встречи — одним вызовом.

compare_players

Суммарные показатели двух игроков за один сезон бок о бок.

data_coverage

Что именно есть в базе данных для каждой лиги и сезона. Используйте его, прежде чем утверждать, что какого-то показателя нет.

predict_match

Вероятность победы/ничьей/поражения для матча по модели, обученной на 23 168 матчах (2015–2025, шесть национальных лиг — Лига чемпионов исключена: её плей-офф формат несопоставим с круговой таблицей). Два кандидата сравнивались лицом к лицу на отложенном валидационном сезоне (логистическая регрессия против классификатора на градиентном бустинге); оставлен тот, у кого лучше валидационный log loss. Честный, не тронутый при выборе модели тестовый результат смотрите в model.metricas_prueba_2025 в ответе самого инструмента.

Матч не обязан уже существовать в базе данных. Текущее Elo каждой команды, недавняя форма и дни отдыха хранятся в снимке team_current_form, который обновляется независимо от любого отдельного матча, — так что это работает как для матча, запланированного на следующую неделю, так и для сыгранного пять лет назад.

{"name": "predict_match", "arguments": {"home_team_id": 529, "away_team_id": 531}}

{
  "local": "Barcelona", "visitante": "Athletic Club",
  "probabilidad_local": 0.779, "probabilidad_empate": 0.145, "probabilidad_visitante": 0.076,
  "modelo": "logistic_regression",
  "advertencia": "Probabilidad estadistica basada en historial, no una garantia..."
}

Обученная модель поставляется в data/predict_model.joblib (несколько КБ — подобранный пайплайн scikit-learn, а не сырые веса). Для переобучения требуется полный пайплайн признаков (conocimiento/ml/), который находится в приватном репозитории проекта, а не здесь, — та же связь, что у data/football.dump с пайплайном извлечения, который его создал.

Пример сеанса

Какая команда выиграла Премьер-лигу в 2015 году?

→ search_team {"query": "Leicester"}
→ get_team_season {"team_id": 46, "league_id": 39, "season": 2015}

«Лестер Сити», с 81 очком: 23 победы, 12 ничьих и 3 поражения — и лишь 42.7% среднего владения мячом, необычно для чемпиона.

Архитектура

MCP host  ──JSON-RPC/stdio──>  server.py  ──>  knowledge/engine.py  ──>  PostgreSQL

server.py владеет протоколом и ничем больше. Вся логика запросов живёт в knowledge/engine.py, который возвращает обычные словари и ничего не знает об MCP, — поэтому его можно тестировать или переиспользовать полностью самостоятельно.

Лицензия

MIT. Футбольные данные происходят из API-Football и перераспространяются здесь в академических целях.

Создано для CC3067 Redes, Universidad del Valle de Guatemala.