Neo4j GraphRAG MCP Server

Neo4j GraphRAG MCP Server

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, `r