Football Knowledge Graph RAG with MCP

Overview

Football Knowledge Graph RAG is a Graph Retrieval-Augmented Generation (Graph RAG) system built using Neo4j, Large Language Models (LLMs), and the Model Context Protocol (MCP).

The system allows users to query a football knowledge graph using natural language. Questions are automatically translated into Cypher queries, executed against Neo4j, and transformed into human-readable answers using an LLM.

In addition, the system provides a Graph Builder that can automatically construct a knowledge graph from natural language text.

System Architecture

Related MCP server: Neo4j Agent Memory MCP Server

Graph RAG Pipeline

User Question
      │
      ▼
Text-to-Cypher (LLM)
      │
      ▼
Cypher Query
      │
      ▼
Neo4j Knowledge Graph
      │
      ▼
Retrieved Data
      │
      ▼
Answer Generation (LLM)
      │
      ▼
Final Response

Graph Builder Pipeline

Natural Language Text
      │
      ▼
Entity & Relationship Extraction (LLM)
      │
      ▼
Structured Graph Data
      │
      ▼
Neo4j Knowledge Graph

Technologies Used

• Python

• Neo4j Graph Database

• OpenRouter API

• Google Gemini 2.5 Flash

• MCP (Model Context Protocol)

• FastMCP

Project Structure

football-knowledge-graph-rag/

├── football_mcp.py
├── graph_rag.py
├── test.py
├── requirements.txt
├── .env.example
├── claude_desktop_config.example.json
└── README.md

Code Documentation

graph_rag.py

This module implements the Graph Retrieval-Augmented Generation (Graph RAG) workflow.

Main Functions

test_connection()

Verifies the connection to the Neo4j database.

generate_cypher(question)

Converts a natural language question into a Cypher query using an LLM.

Example:

Input:

Who are the players of Chelsea?

Generated Cypher:

MATCH (a:Athlete)-[:PLAYS_FOR]->(c:Club)
WHERE c.name = "Chelsea F.C."
RETURN a.name AS athlete
LIMIT 20

execute_cypher(cypher)

Executes a Cypher query against Neo4j and returns the results.

generate_answer(question, data)

Converts retrieved graph data into a natural language response.

graph_rag(question)

Main Graph RAG pipeline:

Question
   ↓
Generate Cypher
   ↓
Execute Cypher
   ↓
Retrieve Graph Data
   ↓
Generate Answer

football_mcp.py

This module implements the MCP server and exposes multiple tools for interacting with the knowledge graph.

Available Tools

ask_graph()

Query the football knowledge graph using natural language.

preview_graph()

Preview entities and relationships before insertion into Neo4j.

build_graph()

Automatically construct a knowledge graph from natural language text.

run_cypher()

Execute custom Cypher queries directly on Neo4j.

project_info()

Display project information.

test.py

Used for testing, experimentation, and development purposes.

Knowledge Graph Schema

Entities

Athlete

Represents football players.

Examples:

Cole Palmer
Bukayo Saka
Bruno Fernandes

Club

Represents football clubs.

Examples:

Chelsea F.C.
Arsenal F.C.
Manchester United F.C.

Country

Represents player nationality or country of origin.

Examples:

England
Germany
Brazil

Relationships

PLAYS_FOR

(Athlete)-[:PLAYS_FOR]->(Club)

Example:

Cole Palmer
    │
PLAYS_FOR
    ▼
Chelsea F.C.

FROM

(Athlete)-[:FROM]->(Country)

Example:

Cole Palmer
    │
FROM
    ▼
England

Cypher Query Logic

The system uses a Text-to-Cypher approach.

Example Question:

Who are the players of Chelsea?

Generated Cypher:

MATCH (a:Athlete)-[:PLAYS_FOR]->(c:Club)
WHERE c.name = "Chelsea F.C."
RETURN a.name AS athlete
LIMIT 20

Example Question:

Which country contributes the most players to Arsenal?

Generated Cypher:

MATCH (a:Athlete)-[:PLAYS_FOR]->(c:Club),
      (a)-[:FROM]->(country:Country)
WHERE c.name = "Arsenal F.C."
RETURN country.name AS country,
       count(*) AS total
ORDER BY total DESC
LIMIT 10

AI Pipeline Explanation

The AI workflow consists of three main stages.

Stage 1 — Natural Language to Cypher

User question:

Who plays for Chelsea?

The LLM translates the question into a valid Cypher query based on the graph schema.

Stage 2 — Graph Retrieval

The generated Cypher query is executed against Neo4j.

Example result:

[
  {
    "athlete": "Cole Palmer"
  },
  {
    "athlete": "Enzo Fernandez"
  }
]

Stage 3 — Natural Language Answer Generation

The retrieved graph data is passed back to the LLM to generate a human-readable response.

Example:

The players currently associated with Chelsea in the knowledge graph are Cole Palmer and Enzo Fernandez.

Installation

Clone the repository:

git clone https://github.com/Fachreza28/football-knowledge-graph-rag.git

cd football-knowledge-graph-rag

Install dependencies:

pip install -r requirements.txt

Configuration

Create a .env file:

NEO4J_URI=neo4j://127.0.0.1:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password

OPENROUTER_API_KEY=your_api_key

MODEL_NAME=google/gemini-2.5-flash

Running the Project

Start the MCP server:

python football_mcp.py

Expected output:

STARTING MCP SERVER...

Example Queries

Who plays for Chelsea?

Who plays for Arsenal?

Which country contributes the most players to Arsenal?

Which players are from England?

Which club does Cole Palmer play for?

Author

Fachreza Aptadhi Kurniawan

Co-Author

Sultan Alamsyah Mubarok

Football Knowledge Graph RAG Project using Neo4j, MCP, Graph RAG, and Large Language Models.