Neo4j GraphRAG MCP Server

An MCP server that extends Neo4j with vector search, fulltext search, and search-augmented Cypher queries for GraphRAG applications.

Inspired by the Neo4j Labs mcp-neo4j-cypher server. This server adds vector search, fulltext search, and the innovative search_cypher_query tool for combining search with graph traversal.

Overview

This server enables LLMs to:

• 🔍 Search Neo4j vector indexes using semantic similarity
• 📝 Search fulltext indexes with Lucene syntax
• ⚡ Combine search with Cypher queries via search_cypher_query
• 🕸️ Execute read-only Cypher queries

Built on LiteLLM for multi-provider embedding support (OpenAI, Azure, Bedrock, Cohere, etc.).

Related: For the official Neo4j MCP Server, see neo4j/mcp. For Neo4j Labs MCP Servers (Cypher, Memory, Data Modeling), see neo4j-contrib/mcp-neo4j.

Installation

# Using pip
pip install mcp-neo4j-graphrag

# Using uv (recommended)
uv pip install mcp-neo4j-graphrag

Configuration

Claude Desktop

Edit the configuration file:

• macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "neo4j-graphrag": {
      "command": "uvx",
      "args": ["mcp-neo4j-graphrag"],
      "env": {
        "NEO4J_URI": "neo4j+s://demo.neo4jlabs.com",
        "NEO4J_USERNAME": "recommendations",
        "NEO4J_PASSWORD": "recommendations",
        "NEO4J_DATABASE": "recommendations",
        "OPENAI_API_KEY": "sk-...",
        "EMBEDDING_MODEL": "text-embedding-ada-002"
      }
    }
  }
}

Note: uvx automatically downloads and runs the package from PyPI. No local installation needed!

Cursor

Edit ~/.cursor/mcp.json or .cursor/mcp.json in your project. Use the same configuration as above.

Reload Configuration

• Claude Desktop: Quit and restart the application
• Cursor: Reload the window (Cmd/Ctrl + Shift + P → "Reload Window")

Tools

get_neo4j_schema_and_indexes

Discover the graph schema, vector indexes, and fulltext indexes.

💡 The agent should automatically call this tool first before using other tools to understand the schema and indexes of the database.

Example prompt:

"What is inside the database?"

vector_search

Semantic similarity search using embeddings.

Parameters: text_query, vector_index, top_k, return_properties

Example prompt:

"What movies are about artificial intelligence?"

fulltext_search

Keyword search with Lucene syntax (AND, OR, wildcards, fuzzy).

Parameters: text_query, fulltext_index, top_k, return_properties

Example prompt:

"find people named Tom"

read_neo4j_cypher

Execute read-only Cypher queries.

Parameters: query, params

Example prompt:

"Show me all genres and how many movies are in each"

search_cypher_query

Combine vector/fulltext search with Cypher queries. Use $vector_embedding and $fulltext_text placeholders.

Parameters: cypher_query, vector_query, fulltext_query, params

Example prompt:

"In one query, what are the directors and genres of the movies about 'time travel adventure' "

Environment Variables

Embedding Providers

Set EMBEDDING_MODEL and the corresponding API key:

Advanced Topics

See docs/ADVANCED.md for:

• Comparison with Neo4j Labs mcp-neo4j-cypher server
• Production features (output sanitization, token limits)
• Detailed tool documentation

License

MIT License