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

Variable	Required	Default	Description
`NEO4J_URI`	Yes	`bolt://localhost:7687`	Neo4j connection URI
`NEO4J_USERNAME`	Yes	`neo4j`	Neo4j username
`NEO4J_PASSWORD`	Yes	`password`	Neo4j password
`NEO4J_DATABASE`	No	`neo4j`	Database name
`EMBEDDING_MODEL`	No	`text-embedding-3-small`	Embedding model (see below)

Embedding Providers

Set EMBEDDING_MODEL and the corresponding API key:

Provider	Model Format	API Key Variable
OpenAI	`text-embedding-ada-002`	`OPENAI_API_KEY`
Azure	`azure/deployment-name`	`AZURE_API_KEY`, `AZURE_API_BASE`
Bedrock	`bedrock/amazon.titan-embed-text-v1`	`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
Cohere	`cohere/embed-english-v3.0`	`COHERE_API_KEY`
Ollama	`ollama/nomic-embed-text`	(none - local)

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

Neo4j GraphRAG MCP Server