Neo4j GraphRAG Server

PyPI version Python 3.10+ License: MIT

An MCP server that extends Neo4j with vector search, fulltext search, search-augmented Cypher queries, write operations, and multimodal image retrieval 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
• ✏️ Execute write Cypher queries (CREATE, MERGE, SET, DELETE)
• 🖼️ Retrieve images stored in Neo4j nodes (multimodal — returns the image directly to the LLM)

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

The examples below use the Neo4j demo recommendations database (movies, actors, directors), which is the same database referenced in the Configuration section above.

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, pre_filter

Use pre_filter to restrict results to nodes matching exact property values (e.g. {"genre": "Drama"}).

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 movies with 'space' or 'galaxy' in the title or plot"

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'?"

write_neo4j_cypher

Execute write Cypher queries (CREATE, MERGE, SET, DELETE, etc.). Returns a summary of counters (nodes created, properties set, etc.).

Parameters: query, params

Example prompt:

"Add a user rating of 4.5 for the movie 'Inception'"

read_node_image

Retrieve a base64-encoded image stored on a Neo4j node and return it as an inline image. Useful for graph databases that store page scans, diagrams, or photos directly on nodes. The LLM receives both the image and selected node properties, enabling visual analysis of graph-stored content.

Parameters: node_element_id, image_property, mime_type, return_properties

Note: This tool requires a database that stores images directly on nodes (as base64). The demo recommendations database does not — it stores external poster URLs instead. See docs/ADVANCED.md for a full example using a document graph where page images are embedded on nodes.

Example prompt:

"Show me page 3 of the AbbVie pipeline document and describe what you see"

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 including write_neo4j_cypher, read_node_image, and vector_search filtering

License

MIT License