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: Graphiti-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

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.