This MCP server provides a vector search capability over a Neo4j graph using OpenAI embeddings. It exposes a single tool, Vector Search, which converts natural language queries into a 1536-dimensional embedding, executes a cosine similarity search against the Neo4j vector index, and returns a ranked list of matching documents with similarity scores. You can invoke this tool from your MCP client or Claude Desktop integration by calling vector_search_neo4j with a natural language prompt such as: vector_search_neo4j(prompt="Find documents about machine learning and neural networks"). Ensure your Neo4j instance has the APOC plugin installed and a 1536-dimensional embedding property on nodes (embedding).

Prerequisites:

• Python 3.8+
• Neo4j 5.0+ with APOC installed
• OpenAI API key
• uv (Python package manager) for fast local setup (optional but recommended)

Install and run using uv (recommended):

1. Install uv if not already installed:

   On macOS and Linux

   curl -LsSf https://astral.sh/uv/install.sh | sh

   On Windows

   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Clone the repository and install dependencies: git clone https://github.com/omarguzmanm/mcp-server-vector-search.git cd mcp-server-vector-search uv venv uv pip install fastmcp neo4j openai python-dotenv sentence-transformers pydantic

3. Configure environment variables (create .env or export variables): NEO4J_URI=bolt://localhost:7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=your_neo4j_password NEO4J_DATABASE=neo4j OPENAI_API_KEY=your_openai_api_key

4. Launch the server:

   Activate virtual environment (example for Linux/macOS)

   source .venv/bin/activate

   Or Windows: .venv\Scripts\activate

   python main.py

If you prefer a direct Python run without uv, you can run:

python main.py

Notes and tips:

• Ensure your Neo4j vector index supports 1536 dimensions for OpenAI embeddings and that nodes have an embedding property containing the vector.
• If you encounter a missing vector index error, create or verify the index with: CREATE VECTOR INDEX embeddableIndex FOR (n:Document) ON (n.embedding) OPTIONS {indexConfig: {vector.dimensions: 1536, vector.similarity_function: 'cosine'}}
• The OpenAI API key is optional in some setups but recommended. If not provided, the default model might be used depending on your code; ensure OPENAI_API_KEY is configured if needed.
• uv provides faster dependency resolution; consider using it in development to accelerate installs and environment management.
• If you run into module-not-found errors, reinstall dependencies within the active environment: uv pip install --force-reinstall fastmcp neo4j openai
• For Claude Desktop integration, you can map the MCP server as shown in the README examples by configuring mcpServers with command and args that start the Python server and pass the needed with/neo4j/pydantic options.