OpenClaw + MCP + Neo4j: Building an AI Agent for YouTube GraphRAG

---

In our previous LBSocial tutorials, we successfully established our underlying data ingestion pipeline: using n8n workflows to automatically collect YouTube video metadata, leveraging Gemini embeddings to represent video content mathematically, and storing it in a Neo4j graph database to build a robust video knowledge graph.

In this edition, we will achieve the ultimate milestone—connecting this existing knowledge graph to our OpenClaw AI agent through a custom Model Context Protocol (MCP) server. This implementation empowers our AI agent to seamlessly query our graph database, interpret complex relationships, execute semantic vector searches, and deliver tailored structured learning paths directly to students via Telegram.  

You can watch the full step-by-step walk-through and see the final live demonstration in the video below:

https://www.youtube.com/watch?v=Dna_DZLC8d0

OpenClaw + MCP + Neo4j: Build an AI Agent for YouTube GraphRAG

1. System Architecture and the Role of MCP

Before diving into code deployment, it is vital to understand how the individual components interact within our GraphRAG ecosystem. The entire workflow runs on a single Google Cloud VM that hosts OpenClaw, n8n, and our custom MCP server application.  

 The system architecture diagram

As shown in the system architecture diagram above, when a user asks a question or requests a learning path on Telegram, the request leaves the Google Cloud environment and enters the OpenClaw runtime. OpenClaw serves as the core reasoning engine and MCP client, determining which tool best matches the user's intent. Once selected, it fires an MCP tool call down to our registered lbsocial-youtube-graphrag stdio MCP server.  

To help you fully visualize this underlying translation process, we have built an interactive simulator below. You can click "Step Forward" to see exactly how a natural language request transforms into a JSON-RPC tool call, compiles into a live Neo4j Cypher query, and resolves back into a student-friendly response.

The custom MCP server functions as an intelligent translation layer. It translates JSON-RPC tool calls from the AI agent into optimized Cypher graph database queries or vector search requests. For instance, a search query triggers an embedding request to the Gemini Embedding API, generating a 768-dimensional vector representing the user's question. This vector is then pushed to Neo4j via a vector index search, complemented by traditional Cypher graph traversals to gather relevant Channel and Topic contexts. The resulting structured records are returned to the MCP server, passed back to OpenClaw as a formatted ToolResult, and rendered as student-friendly, natural-language responses in Telegram.  

It is important to emphasize that a stdio MCP server is not a long-running web API server listening constantly on an HTTP port. Instead, it functions as a highly portable Python toolset, managed and executed on demand by the OpenClaw gateway via standard input/output streams.  

2. Prerequisites and Code Repository Isolation

To proceed with deployment, connect to your Google Cloud VM using VS Code Remote-SSH. We will keep the environment clean by using the dedicated repository that contains all custom workflows and MCP configurations.  

First, clone the official LBSocial repository or pull the latest changes if you have already cloned it previously:  

cd /home/info

# If cloning for the first time
git clone https://github.com/lbsocial/openclaw-n8n-neo4j-workflows.git

# If updating an existing repository
cd /home/info/openclaw-n8n-neo4j-workflows
git pull

Once up-to-date, navigate into the custom MCP folder specifically built for our YouTube GraphRAG setup:  

cd /home/info/openclaw-n8n-neo4j-workflows/mcp/youtube-graphrag

Inside this folder, you will find essential project files including server.py (which defines our specialized tool menu), configuration templates, and testing scripts.  

3. Python Environment Management with UV

To guarantee reproducibility and clean dependency separation, we utilize uv, a blisteringly fast Python package installer and workflow manager.  

Check if uv is installed on your cloud machine:  

uv --version
which uv

If uv is missing, run the standalone installation script and refresh your shell configurations:  

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Now, synchronize your virtual environment and install all necessary dependencies specified in pyproject.toml and uv.lock:  

uv --directory /home/info/openclaw-n8n-neo4j-workflows/mcp/youtube-graphrag sync

This sets up an isolated .venv folder containing the FastMCP frameworks, Neo4j drivers, and Google GenAI packages required for the server to function.  

4. Secure Environment Configuration

Our custom MCP server requires access credentials for both Neo4j AuraDB and the Gemini API. Open the VS Code file explorer, locate the project folder, and create a production .env file from the provided template:  

# Rename the example template to activate it
cp .env.example .env

Open the newly created .env file in the VS Code editor and configure your secrets. Ensure you strip away any unused configurations like OpenAI settings, as we are strictly standardized on Gemini for this series:  

NEO4J_URI=neo4j+s://xxxxxx.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your_secure_neo4j_password
GEMINI_API_KEY=your_gemini_api_key

YOUTUBE_VIDEO_VECTOR_INDEX=video_embeddings
YOUTUBE_VIDEO_LABEL=Video
YOUTUBE_CHANNEL_LABEL=Channel
YOUTUBE_TOPIC_LABEL=Topic
YOUTUBE_CHANNEL_TO_VIDEO_REL=PUBLISHED
YOUTUBE_VIDEO_TO_TOPIC_REL=HAS_TOPIC
YOUTUBE_VIDEO_EMBEDDING_PROPERTY=embedding
YOUTUBE_VIDEO_ID_PROPERTY=video_id
YOUTUBE_VIDEO_TITLE_PROPERTY=title
YOUTUBE_VIDEO_URL_PROPERTY=url
YOUTUBE_VIDEO_DOCUMENT_TEXT_PROPERTY=document_text
YOUTUBE_VIDEO_PUBLISHED_AT_PROPERTY=published_at
YOUTUBE_CHANNEL_TITLE_PROPERTY=channel_title
YOUTUBE_TOPIC_NAME_PROPERTY=name
NEO4J_SCHEMA_SAMPLE_SIZE=100

To lock down credentials and protect sensitive API keys, enforce restrictive read/write permissions directly via your terminal:  

chmod 600 /home/info/openclaw-n8n-neo4j-workflows/mcp/youtube-graphrag/.env

The credentials are stored in the .env file

Tip: Always place secrets in the local .env file rather than passing them as cleartext inline arguments in the OpenClaw configuration registry, thereby protecting your keys from exposure via administrative CLI inspection commands.  

5. Initializing the Neo4j Vector Index

While our prior n8n ingestion pipeline handles writing structural video nodes, metadata, and raw Video.embedding properties into AuraDB, it does not automatically construct database-level indexes. Without an active index, any attempt by an agent to perform semantic searches will result in a schema exception stating that video_embeddings does not exist.  

The YouTube knowledge graph in Neo4j

Log in to your Neo4j Browser console and execute the following Cypher query to establish a cosine similarity vector index on the video node embeddings:  

CREATE VECTOR INDEX video_embeddings IF NOT EXISTS
FOR (v:Video)
ON (v.embedding)
OPTIONS {
  indexConfig: {
    `vector.dimensions`: 768,
    `vector.similarity_function`: 'cosine'
  }
};

Verify that the index has successfully built and shifted from a data population state into an operational status:  

SHOW INDEXES
YIELD name, type, state, labelsOrTypes, properties
WHERE name = 'video_embeddings';

Ensure that the returned configuration indicates a VECTOR type, targets the ["Video"] label and the ["embedding"] property, and has an ONLINE state.  

6. Performing a Local Smoke Test via Interactive Menu

Before introducing OpenClaw into the loop, verify that the custom MCP server can successfully authenticate and retrieve records from your backend. Instead of running a single automated query, we will use the interactive tool menu to test individual MCP functions step by step, exactly as shown in the video tutorial.

Run the local tool menu script via your terminal:

uv --directory /home/info/openclaw-n8n-neo4j-workflows/mcp/youtube-graphrag run python local_tool_menu.py

The local MCP test

This will boot up the MCP server in stdio mode and display an interactive terminal menu featuring our 8 predefined GraphRAG tools. Let's perform a quick verification sequence to ensure the data pipeline is solid:  

• Type 1 (get_neo4j_schema_and_indexes): This confirms your database connection. It should successfully return your node labels (Video, Channel, Topic) and relationships, and confirm that the vector embedding index is active.  

• Type 2 (search_youtube_videos): Test the Gemini embedding API and Neo4j vector search. When prompted, enter a query like "n8n" and request 2 results. The server will generate an embedding, query the graph, and return matching video titles (e.g., "Deploying n8n on Google Cloud via Docker") along with their descriptions and URLs.  

• Type 4 (get_recent_youtube_videos): Request 1 recent video to ensure the server can execute standard Cypher traversals against the latest ingested metadata.  

Once you verify the returned video records, type quit to exit the menu. A successful validation pass here guarantees that all underlying credentials, Neo4j connections, and Gemini APIs are functioning properly before we hand control of the tool over to the OpenClaw agent.  

7. Registering the Custom MCP Server with OpenClaw

Now that the server is working locally, register it as an official stdio toolset within the OpenClaw registry. It is recommended to supply the absolute path of the uv executable to prevent environment PATH resolution conflicts during runtime executions:  

openclaw mcp set lbsocial-youtube-graphrag '{
  "command": "/home/info/.local/bin/uv",
  "args": ["run", "python", "server.py"],
  "cwd": "/home/info/openclaw-n8n-neo4j-workflows/mcp/youtube-graphrag"
}'

Validate that the registration was logged correctly by inspecting the global OpenClaw configuration profile:  

openclaw mcp list
openclaw mcp show lbsocial-youtube-graphrag --json

The MCP server has been successfully registered

8. Real-World Testing via Telegram

With the integration complete, switch to Telegram to chat with your AI assistant bot. We can explicitly direct OpenClaw to leverage the newly registered server for verification testing.  

Database Schema Audit: To verify full structural visibility, send:

Use the lbsocial-youtube-graphrag MCP server to inspect the Neo4j schema and available indexes. 

The agent will return a complete layout detailing the Video, Channel, and Topic node structures, as well as the ONLINE status of your vector search systems.  

9. Deploying an OpenClaw Skill for Automatic Tool Routing

Forcing users to explicitly type out the name of an MCP server in everyday conversations creates an unnatural user experience. To streamline routing, activate the skill-creator tool within Telegram by typing skill creator. Paste the following structured Markdown prompt template to build an automated workspace routing engine:  

# LBSocial YouTube GraphRAG Assistant

## Purpose
Use this skill when the user asks about LBSocial YouTube tutorials, OpenClaw tutorials, n8n workflows, Neo4j graph databases, Gemini embeddings, MCP servers, GraphRAG, AI agents, or learning paths based on LBSocial video content.

## MCP Server
Use the `lbsocial-youtube-graphrag` MCP server when answering these questions.

## Tool Selection
- Use `search_youtube_videos` when the user asks for relevant videos, tutorials, examples, or resources.
- Use `recommend_learning_path` when the user asks how to learn a topic step by step.
- Use `get_related_videos` when the user starts from a known video and asks what to watch next.
- Use `get_video_context` when the user asks about one specific video or title phrase.
- Use `get_neo4j_schema_and_indexes` for debugging graph schema or vector indexes.
- Use `run_readonly_cypher` only for safe analytical questions, such as counts by topic. Do not use for write or admin operations.

## Response Formatting
Do not expose raw JSON. Format video search results as a clean list containing Title, Topic, Short Explanation, and Watch URL. Format learning paths as step-by-step progressions. Always include clean YouTube URLs to allow Telegram to generate automatic previews.

Once saved, OpenClaw compiles this instruction profile into your local workspace folder:

/home/info/.openclaw/workspace/skills/lbsocial-youtube-graphrag/SKILL.md

Now, test the routing by asking a standard natural language query without mentioning the underlying tools:

I want to learn OpenClaw and also n8n. Okay, recommend some videos.   

OpenClaw will automatically activate the skill, select the correct tool, query your Neo4j GraphRAG index, and output a highly logical curriculum complete with clear step-by-step explanations and clean video URLs.

OpenClaw effectively uses MCP to answer questions.

Summary

This step-by-step tutorial covers configuring Gemini API credentials, testing the server locally with an interactive menu, and registering the MCP server with OpenClaw. Discover how to use the Skill Creator so your AI agent can rely on your own YouTube video content to generate structured learning paths and answer conceptual questions directly in Telegram.  

Source Code & Resources:

Please note that the GitHub repository linked below specifically contains the custom MCP server Python code (mcp/youtube-graphrag) built for this episode.

👉 MCP Server Code Repository: lbsocial/openclaw-n8n-neo4j-workflows