# Neo4j GraphRAG MCP Server

[![PyPI version](https://badge.fury.io/py/mcp-neo4j-graphrag.svg)](https://pypi.org/project/mcp-neo4j-graphrag/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/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`](https://github.com/neo4j-contrib/mcp-neo4j/tree/main/servers/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](https://docs.litellm.ai/) for multi-provider embedding support (OpenAI, Azure, Bedrock, Cohere, etc.).

> **Related:** For the official Neo4j MCP Server, see [neo4j/mcp](https://github.com/neo4j/mcp). For Neo4j Labs MCP Servers (Cypher, Memory, Data Modeling), see [neo4j-contrib/mcp-neo4j](https://github.com/neo4j-contrib/mcp-neo4j).

## Installation

```bash
# 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`

```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](https://demo.neo4jlabs.com) (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](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](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