GraphRAG MCP Node

This package serves as a Model Context Protocol endpoint, architected to query a sophisticated, dual-database retrieval infrastructure. It synthesizes data retrieval from Neo4j, functioning as the graph knowledge store, and Qdrant, serving as the dense vector index, for superior context sourcing.

Core Functionality

GraphRAG MCP provides unified access for Large Language Models (LLMs) to a retrieval engine built upon the complementary strengths of graph modeling (Neo4j) and high-dimensional vector similarity search (Qdrant). Key capabilities include:

• Vector similarity queries leveraging document embeddings.
• Contextual augmentation derived from traversing ontological relationships in the graph.
• Convergent search methods blending vector closeness with structural pathfinding.
• Full adherence to the Model Context Protocol standard, ensuring plug-and-play compatibility with MCP-aware client applications.

Key Features

• Vector Retrieval: Executes semantic lookups utilizing sentence encodings indexed in Qdrant.
• Graph Traversal: Performs knowledge expansion by navigating connections stored in Neo4j.
• Blended Search: Combines both vector proximity and graph structure evidence.
• LLM Interoperability: Exposes dedicated MCP tools and informational resources.
• Metadata Exposure: Provides schema documentation for Neo4j and collection metadata for Qdrant.

Operational Requirements

• Python environment version 3.12 or newer is mandatory.
• A running instance of Neo4j, accessible at the default URI (localhost:7687).
• A running instance of Qdrant, accessible at the default URI (localhost:6333).
• Pre-processed and indexed document data across both persistence layers.

Deployment Instructions

Rapid Initialization

1. Obtain the source code repository: bash git clone https://github.com/rileylemm/graphrag_mcp.git cd graphrag_mcp

2. Resolve dependencies using uv: bash uv install

3. Configure access parameters in the .env configuration file: env # Neo4j Connection Settings NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=password

# Qdrant Connection Settings QDRANT_HOST=localhost QDRANT_PORT=6333 QDRANT_COLLECTION=document_chunks

1. Initiate the server process: bash uv run main.py

Advanced Configuration Reference

For exhaustive instructions on establishing and populating the underlying hybrid data infrastructure, consult the supplementary project repository: GraphRAG Hybrid Database

Database Provisioning (Docker Examples)

1. Starting Neo4j: bash docker run \ --name neo4j_instance \ -p 7474:7474 -p 7687:7687 \ -e NEO4J_AUTH=neo4j/password \ -v $HOME/neo4j_data:/data \ neo4j:latest

2. Starting Qdrant: bash docker run -p 6333:6333 -p 6334:6334 \ -v $HOME/qdrant_storage:/qdrant/storage \ qdrant/qdrant

Data Ingestion Workflow

To populate both data stores:

1. Source document preparation.
2. Generation of vector representations using sentence transformers.
3. Persistence of structured document data and relationships within Neo4j.
4. Storage of vector embeddings corresponding to document segments in Qdrant.

Detailed scripts for this indexing process are available in the GraphRAG Hybrid Database documentation.

Client Integration (MCP Consumers)

Configuration for Claude or Cursor

1. Ensure the launch script has execution permissions: bash chmod +x run_server.sh

2. Modify the client's MCP configuration file (e.g., ~/.cursor/mcp.json):

{ "mcpServers": { "GraphRAG": { "command": "/path/to/graphrag_mcp/run_server.sh", "args": [] } } }

1. Relaunch the consuming application.

Available Operations (MCP Tools)

The server exposes the following endpoints for programmatic access by LLMs:

1. search_documentation - Executes a purely semantic search against indexed content. python # Example invocation within an MCP context response = search_documentation( query="Explain the graph context expansion mechanism", limit=5, category="technical_docs" )

2. hybrid_search - Performs a unified search incorporating vector proximity and graph structure validation. python # Example invocation within an MCP context response = hybrid_search( query="Find data relating vector similarity to structural paths", limit=10, category=None, expand_context=True )

Provided Knowledge Endpoints (MCP Resources)

The following URI endpoints offer introspective metadata about the underlying data systems:

1. https://graphrag.db/schema/neo4j - Schema definition for the underlying Neo4j graph model.
2. https://graphrag.db/collection/qdrant - Metadata describing the vector index configuration in Qdrant.

Debugging Guidance

• Connectivity Issues: Confirm that both Neo4j and Qdrant services are operational and reachable.
• No Search Results: Validate that the document corpus has been successfully indexed in both databases.
• Dependency Errors: Execute uv install to resolve missing Python packages.
• Authentication Failures: Review and correct database credentials specified in the .env file.

Contribution Guidelines

We welcome external contributions. Please submit proposed enhancements via a Pull Request.

Licensing

Distributed under the terms of the MIT License.

Copyright (c) 2025 Riley Lemm

(Standard MIT License boilerplate text omitted for brevity...)

Acknowledgment

Credit to Riley Lemm is requested if this MCP server or its derived components are used in operational systems, with a link directed back to the source repository: https://github.com/rileylemm/graphrag_mcp.