Skip to main content
Glama
neo4j-field

Neo4j GraphRAG MCP Server

by neo4j-field
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Neo4j GraphRAG MCP 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.

Related MCP server: Neo4j YASS MCP

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

Available Tools

5 tools
get_neo4j_schema_and_indexesGet Neo4j Schema & IndexesA
Read-onlyIdempotent

Returns Neo4j graph schema with search indexes and property size warnings.

IMPORTANT: Call this tool BEFORE using any search tools (vector_search, fulltext_search, search_cypher_query).

This tool provides:

  • Vector & fulltext indexes (for search)

  • Node/relationship schemas with property types

  • Warnings for large properties (helps choose efficient return_properties)

Property size warnings help you avoid token limits when using search tools. For example, if a property has warning "avg ~100-200KB", avoid returning it unless necessary.

You should only provide a sample_size value if requested by the user, or tuning performance.

ParametersJSON Schema
NameRequiredDescriptionDefault
sample_sizeNoThe sample size used to infer the graph schema and property sizes. Larger samples are slower but more accurate.

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description adds context about sample_size affecting speed/accuracy and warns about token limits from large properties, going beyond the annotations. No contradiction found.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The main purpose is front-loaded, followed by a bulleted breakdown and a concrete example. It is moderately concise and well-structured, though slightly verbose with some redundancy between the bullet points and the follow-up example.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Even without an output schema, the description conveys the key outputs (indexes, schemas, warnings) and explains why they matter. It gives enough context for an agent to understand when to call it, what to expect, and how to use sample_size effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already provides complete coverage of sample_size with a description of its effect on speed and accuracy. The description adds guidance on when to provide it (only if requested by user or for performance tuning), which is extra value beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns Neo4j graph schema with search indexes and property size warnings. It uses a specific verb ('Returns') and resource ('Neo4j graph schema'), and distinguishes itself from sibling search tools by positioning itself as a prerequisite step.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to call this tool BEFORE using vector_search, fulltext_search, or search_cypher_query, providing clear when-to-use guidance. It also explains how property size warnings help choose return_properties, reinforcing practical usage context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

read_neo4j_cypherRead Neo4j CypherB
Read-onlyIdempotent

Execute a read Cypher query on the Neo4j database.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesThe Cypher query to execute.
paramsNoThe parameters to pass to the Cypher query.

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description only restates the read-only nature already captured by annotations (readOnlyHint, idempotentHint, destructiveHint). It adds no extra context about query execution, result formatting, error handling, or any potential side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, clear sentence conveys the purpose without wasted words. It is front-loaded with the verb and resource, making it easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is relatively simple and the annotations cover safety. However, the description is minimal—it doesn't mention what the query returns or that params is optional (though the schema does). Given no output schema and no usage guidance, the description could provide a bit more context about result expectations or common use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides complete descriptions for both parameters (query and params), so the baseline is 3. The description does not elaborate on parameter usage or add any additional semantic meaning.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly defines the action ('execute') and resource ('read Cypher query on the Neo4j database'), easily distinguishing it from siblings like write_neo4j_cypher and the specialized search tools. The 'read' qualifier immediately signals its scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description offers no guidance on when to choose this tool over alternatives. It doesn't mention that raw Cypher should be used for arbitrary reads or that search tools are for specific query patterns. There are no explicit exclusions or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_cypher_querySearch-Augmented Cypher QueryA
Read-onlyIdempotent

Execute a Cypher query that uses vector and/or fulltext search indexes.

This powerful tool allows you to:

  1. Use vector search ($vector_embedding) and/or fulltext search ($fulltext_text) in Cypher

  2. Post-filter large result sets (fetch 100-1000, filter with WHERE)

  3. Combine search with graph traversal

  4. Aggregate over search results

Example:

search_cypher_query(
    cypher_query='''
        CALL db.index.vector.queryNodes('chunk_embedding_vector', 500, $vector_embedding)
        YIELD node, score
        WHERE score > 0.75
        MATCH (node)-[:BELONGS_TO]->(d:Document)
        WHERE d.year >= 2020
        RETURN node.chunkId, d.title, score
        ORDER BY score DESC
        LIMIT 20
    ''',
    vector_query="student requirements"
)

Placeholders:

  • $vector_embedding: Replaced with embedding vector

  • $fulltext_text: Replaced with text string for fulltext

ParametersJSON Schema
NameRequiredDescriptionDefault
cypher_queryYesCypher query using $vector_embedding and/or $fulltext_text placeholders.
vector_queryNoText query to embed for vector search. Use $vector_embedding placeholder in Cypher.
fulltext_queryNoText query for fulltext search. Use $fulltext_text placeholder in Cypher.
paramsNoAdditional parameters for the Cypher query.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context beyond annotations by explaining placeholder substitution (e.g., $vector_embedding replaced with embedding vector) and typical fetch sizes (100-1000). It also describes post-filtering behavior with WHERE. This extra detail is valuable and not redundant with the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a bulleted list, an example, and a placeholder section. It is somewhat long due to the example, but every section serves a purpose. The front-loading of the core statement is good, and the example is necessary for a complex tool. It is concise enough given the tool's complexity, but not as tight as a two-sentence description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having no output schema, the description compensates with a rich example that shows the return shape and usage patterns. It covers the main combinations (vector/fulltext, post-filtering, traversal, aggregation) and the placeholder mechanism. Minor gaps exist, such as not explaining the 'params' object's possible contents or behavior when both vector and fulltext are used simultaneously, but overall it is sufficiently complete for a 4-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers all parameters, so the baseline is 3. The description adds semantic value by explaining how the placeholders in cypher_query relate to the vector_query and fulltext_query parameters, including the exact replacement behavior. It also demonstrates usage via the example. However, the 'params' object is not elaborated beyond its schema description, so the added value is not maximal.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes a Cypher query enhanced with vector and/or fulltext search indexes. It lists four specific capabilities and distinguishes itself from sibling tools like vector_search and fulltext_search by combining search with graph traversal, post-filtering, and aggregation. The verb 'execute' and resource 'Cyper query' are explicit, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool: when you need to post-filter large result sets, combine search with traversal, or aggregate over search results. However, it lacks explicit exclusions or direct comparisons to alternatives, such as 'use read_neo4j_cypher for non-search queries.' The example implies but does not explicitly state the alternative scenarios, so it falls short of a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv0.3.0
    • First observedfulltext_search
    • First observedget_neo4j_schema_and_indexes
    • First observedread_neo4j_cypher
    • First observedsearch_cypher_query
    • First observedvector_search
Deploy Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Scored across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose with no overlap: fulltext_search uses Lucene queries, vector_search uses embeddings, search_cypher_query combines both with graph traversal, read_neo4j_cypher handles general read queries, and get_neo4j_schema_and_indexes provides metadata. The descriptions explicitly differentiate their use cases and when to apply each, preventing confusion.

Naming Consistency5/5

All tool names follow a consistent snake_case pattern with clear verb_noun or noun_verb structures: fulltext_search, vector_search, search_cypher_query, read_neo4j_cypher, get_neo4j_schema_and_indexes. The naming is predictable and readable, making it easy for agents to infer functionality.

Tool Count5/5

With 5 tools, this server is well-scoped for Neo4j GraphRAG operations. It covers essential search methods (fulltext, vector, hybrid), general querying, and schema inspection without being overly sparse or bloated. Each tool serves a unique and necessary function in the workflow.

Completeness4/5

The toolset provides strong coverage for search and querying in a Neo4j GraphRAG context, including schema inspection, multiple search types, and flexible Cypher execution. A minor gap is the lack of write operations (e.g., create/update nodes), but this aligns with a read-focused RAG server, and agents can work around this limitation.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Neo4j YASS MCP

    hdjebar
    A
    license
    Not graded
    quality
    C
    maintenance
    Production-ready MCP server for Neo4j graph databases, enabling natural language to Cypher query translation with enterprise security and async performance.
    MIT

  • Neo4j MCP Server

    alvaropaco
    A
    license
    A
    quality
    B
    maintenance
    MCP server for Neo4j that provides abstract graph operations for LLMs, enabling safe and consistent interaction with Neo4j databases through tools like search, insert, update, delete, and schema introspection.
    8
    MIT