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

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

Step 1 — Start Neo4j

Make sure your Neo4j database is running.

Default Neo4j URLs:

http://localhost:7474
bolt://localhost:7687

Verify the database status is Running before continuing.

---

Step 2 — Start the MCP Server

Open a terminal in the project directory and run:

py football_mcp.py

Expected output:

STARTING MCP SERVER...
INFO: Started server process
INFO: Waiting for application startup
INFO: Application startup complete

The MCP server will start and expose the Football Knowledge Graph tools through the Streamable HTTP transport.

Available tools:

• ask_graph()
• project_info()
• preview_graph()
• build_graph()
• run_cypher()

---

Tunnel Client Configuration

Before running the tunnel client, you must create and configure a profile that points to the local MCP server.

Step 1 — Login

Authenticate the tunnel client with your OpenAI account:

.\tunnel-client login

Expected output:

Login successful.

---

Step 2 — Create a Profile

Create a new profile named football:

.\tunnel-client profile create football

Expected output:

Profile created: football

---

Step 3 — Configure the Profile

Configure the profile to target the local MCP server:

.\tunnel-client profile set football --target http://127.0.0.1:8000

Verify the configuration:

.\tunnel-client profile show football

Expected output:

Profile: football

Target:
http://127.0.0.1:8000

Status:
Configured

---

Step 4 — Set the Active Profile

.\tunnel-client profile use football

Verify:

.\tunnel-client profile current

Expected output:

football

---

Step 5 — Verify Available Profiles

.\tunnel-client profile list

Expected output:

football
default

---

Running the Tunnel

After the MCP server is running and the profile has been configured, start the tunnel:

.\tunnel-client run --profile football

Expected output:

Tunnel Connected

Profile:
football

Target:
http://127.0.0.1:8000

The tunnel client will securely expose the local MCP server to ChatGPT through the configured connector.

---

Tunnel Architecture

ChatGPT
    │
    ▼
OpenAI Connector
    │
    ▼
Tunnel Client
    │
    ▼
Football MCP Server
(http://127.0.0.1:8000)
    │
    ▼
Neo4j Database

Step 3 — Start the Tunnel Client

Open a second terminal and run:

.\tunnel-client run --profile football

Expected output:

Tunnel Connected
Profile: football
Target: http://127.0.0.1:8000

The tunnel client will connect ChatGPT to the locally running MCP server.

---

Step 4 — Verify the Connection

Open ChatGPT and execute:

UAS_GRAPH project info

Expected output:

Football Knowledge Graph

Data Source:
- Wikidata
- DBpedia

Entity:
- Athlete
- Club
- Country

Graph Analytics:
- Degree Centrality
- Jaccard Similarity
- Louvain Community Detection

Graph Machine Learning:
- FastRP Embedding
- KNN Similarity
- K-Means Clustering

If the information is displayed successfully, the MCP server, tunnel client, and ChatGPT connector are properly connected.

---

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.