Neo4j Prefiltering Vector Search MCP Server

An MCP (Model Context Protocol) server that automatically discovers vector indexes in a Neo4j database and exposes each one as a semantic search tool. Built with FastMCP and LangChain embeddings, so it works with any embedding provider out of the box.

How It Works

On startup the server:

1. Connects to Neo4j and runs SHOW INDEXES to find every VECTOR index.
2. Samples one node per indexed property to detect its type (string, numeric, date, bool, or vector).
3. Identifies the embedding property and the remaining filterable metadata properties.
4. Registers an MCP tool search_<index_name> for each discovered index, complete with a dynamically generated description listing the available filters.

If no vector indexes are found, the server exits with an error.

Prerequisites

• Python 3.10+
• A running Neo4j instance (5.x+ with vector index support)
• At least one vector index already created in the database
• An API key or credentials for your chosen embedding provider

Installation

First, clone the repository:

git clone https://github.com/tomasonjo/neo4j-prefiltering-mcp.git
cd neo4j-prefiltering-mcp

Using uvx (recommended)

No installation needed — just run it directly from the local folder:

uvx --from /path/to/neo4j-prefiltering-mcp neo4j-prefiltering-mcp

Using pip

pip install /path/to/neo4j-prefiltering-mcp

Then run:

neo4j-prefiltering-mcp

Embedding providers

The base package does not include an embedding provider. Install the one you need as an extra:

# OpenAI
pip install "/path/to/neo4j-prefiltering-mcp[openai]"

# Cohere
pip install "/path/to/neo4j-prefiltering-mcp[cohere]"

# HuggingFace
pip install "/path/to/neo4j-prefiltering-mcp[huggingface]"

Or with uvx:

uvx --from /path/to/neo4j-prefiltering-mcp --with langchain-openai neo4j-prefiltering-mcp

Configuration

All configuration is done through environment variables.

The EMBEDDING_MODEL value is passed directly to langchain.embeddings.init_embeddings(). Any provider string it supports will work:

# OpenAI
export EMBEDDING_MODEL="openai:text-embedding-3-small"

# Cohere
export EMBEDDING_MODEL="cohere:embed-english-v3.0"

# HuggingFace
export EMBEDDING_MODEL="huggingface:BAAI/bge-small-en-v1.5"

Make sure the corresponding provider SDK and API key env var are set (e.g. OPENAI_API_KEY, COHERE_API_KEY).

Usage

Claude Desktop

Add the server to your claude_desktop_config.json:

{
  "mcpServers": {
    "neo4j-vector": {
      "command": "uvx",
      "args": ["--from", "/path/to/neo4j-prefiltering-mcp", "--with", "langchain-openai", "neo4j-prefiltering-mcp"],
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USER": "neo4j",
        "NEO4J_PASSWORD": "your-password",
        "NEO4J_DATABASE": "neo4j",
        "EMBEDDING_MODEL": "openai:text-embedding-3-small",
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Code

claude mcp add neo4j-vector -- uvx --from /path/to/neo4j-prefiltering-mcp --with langchain-openai neo4j-prefiltering-mcp

Standalone

neo4j-prefiltering-mcp

The server communicates over stdio by default, which is the standard transport for local MCP tool servers.

Cursor / Continue / Other MCP Clients

Point the client at the server as a stdio server. The exact config format varies by client — consult its docs and use the command + args pattern shown above.

Tool Interface

Each discovered index is exposed as a tool with the following parameters:

Filter Types

The server infers filter types by sampling a node from each index:

Both min and max are optional within a range filter — you can supply either or both.

Example Tool Call

Given an index called news_articles on :Article nodes with metadata properties language (string) and sentiment (float):

{
  "name": "search_news_articles",
  "arguments": {
    "query": "recent breakthroughs in fusion energy",
    "top_k": 5,
    "filters": {
      "language": "en",
      "sentiment": { "min": 0.6 }
    }
  }
}

Response Format

The tool returns a JSON array of results, each containing the matched node's properties (minus the raw embedding vector) and a similarity score:

[
  {
    "doc": {
      "title": "Fusion Milestone Reached at NIF",
      "language": "en",
      "sentiment": 0.92,
      "published": "2025-01-15"
    },
    "score": 0.941
  }
]

Project Structure

.
├── pyproject.toml
├── src/
│   └── neo4j_prefiltering_mcp/
│       ├── __init__.py
│       └── server.py
└── README.md

License

MIT