Football Intelligence MCP

모든 MCP 호스트(Claude Desktop, Claude Code 또는 맞춤형 챗봇)에 2010년부터 2025년까지 유럽 7대 상위 리그의 36,982경기를 아우르는 선별된 역사적 축구 데이터베이스에 대한 액세스를 제공하는 로컬 Model Context Protocol 서버입니다.

프로토콜은 MCP SDK를 사용하지 않고 JSON-RPC 2.0 위에 직접 구현됩니다. 모든 메시지는 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

서버는 stdio를 통해 JSON-RPC로 통신합니다. 일반적으로 수동이 아닌 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는 계산을 해당 날짜보다 엄격히 이전의 경기로 제한하므로 과거 어느 시점의 팀 상태를 재구성할 수 있습니다. 이는 예측 피처를 구축할 때 선견 편향(look-ahead bias)을 방지하는 장치입니다.

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

get_head_to_head

두 팀 간의 승/무/패 균형, 가장 최근 맞대결, 그리고 전체 역사에 걸친 팀별 평균(경기당 골, 옐로/레드 카드, 파울, 코너) — 예측 숫자뿐만 아니라 베팅 결정에 유용한 맥락입니다. 카드/파울/코너는 2015년 이후 경기에만 사용할 수 있습니다. 통계가 없는 경기는 해당 평균에서 제외되며 0으로 계산되지 않습니다.

get_team_season

최종 리그 순위, 승점 및 골과 함께 슛, 점유율, 코너 및 패스 정확도의 경기당 평균.

시즌은 시작 연도로 명명됩니다: 2024는 2024-25 시즌을 의미합니다.

get_player_season

경기 수준 기록에서 집계된 시즌별 선수 합계: 골, 어시스트, 출전 시간, 슛, 키패스, 카드 및 평균 평점.

compare_teams

한 번의 호출로 두 팀의 최근 폼과 맞대결 기록.

compare_players

같은 시즌 두 선수의 합계를 나란히 비교.

data_coverage

리그 및 시즌별로 데이터베이스에 실제로 무엇이 존재하는지. 데이터 포인트가 누락되었다고 주장하기 전에 사용하세요.

predict_match

23,168경기(2015–2025, 6개 국내 리그 — 챔피언스 리그 제외, 녹아웃 형식은 라운드로빈 테이블과 비교할 수 없음)로 훈련된 모델의 경기 승/무/패 확률. 두 후보(로지스틱 회귀 vs. 그래디언트 부스티드 트리 분류기)가 보류된 검증 시즌에서 정면 비교되었으며, 검증 로그 손실이 더 좋은 모델이 채택되었습니다. 선택 중에 절대 건드리지 않은 정직한 테스트 점수는 도구 자체 응답의 model.metricas_prueba_2025를 참조하세요.

경기가 데이터베이스에 이미 존재할 필요는 없습니다. 각 팀의 현재 Elo, 최근 폼 및 휴식 일수는 team_current_form 스냅샷에 유지되며 단일 경기와 독립적으로 갱신됩니다 — 따라서 다음 주에 예정된 경기든 5년 전에 치러진 경기든 동일하게 작동합니다.

{"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에 포함되어 있습니다(몇 KB — 원시 가중치가 아닌 피팅된 scikit-learn 파이프라인). 재훈련에는 전체 피처 파이프라인(conocimiento/ml/)이 필요하며, 이는 여기가 아닌 비공개 프로젝트 저장소에 있습니다 — data/football.dump와 이를 구축한 추출 파이프라인의 관계와 동일합니다.

예시 세션

2015년 프리미어 리그에서 우승한 팀은?

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

레스터 시티, 23승 12무 3패로 81승점 — 그리고 평균 점유율 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를 위해 제작되었습니다.