MCP Neo4j Client Examples

Two example clients that demonstrate different approaches to connecting to the neo4j-cypher MCP server:

1. Basic Client with Ollama (mcp_neo4j_client.py) - Simple client using Ollama for one-shot query generation
2. Interactive Agent with ReAct Pattern (interactive_agent.py) - Advanced agent using Ollama with schema context for interactive queries (same pattern as the backend)

Directory

This client is located in sample-client/ directory.

Prerequisites

1. Python 3.10+
2. uv package manager (>= 0.4.0)
3. Neo4j MCP server running in HTTP mode
4. Ollama running locally with the gpt-oss:120b-cloud model

Installation

Install uv (if not already installed)

# Using the standalone installer (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using Homebrew on macOS
brew install uv

# Or using pip
pip install uv

Install dependencies

Navigate to the sample-client directory:

cd sample-client

Then sync dependencies (this creates the venv and installs everything):

# Sync dependencies - creates .venv and installs all dependencies
uv sync

This will:

• Create a .venv virtual environment if it doesn't exist
• Install all dependencies from pyproject.toml
• Generate/update uv.lock for reproducible builds

Quick Run (No Installation)

You can also run directly without syncing:

uv run mcp_neo4j_client.py

This automatically handles the environment and dependencies.

Setup

1. Start the Neo4j MCP Server

Using Docker (recommended):

docker run -p 8000:8000 \
  -e NEO4J_URI=bolt://host.docker.internal:7687 \
  -e NEO4J_USERNAME=neo4j \
  -e NEO4J_PASSWORD=password \
  -e NEO4J_TRANSPORT=http \
  -e NEO4J_MCP_SERVER_HOST=0.0.0.0 \
  -e NEO4J_MCP_SERVER_PORT=8000 \
  -e NEO4J_MCP_SERVER_PATH=/api/mcp/ \
  mcp/neo4j-cypher:latest

Or using the local server from ../mcp-neo4j/servers/mcp-neo4j-cypher/:

cd ../mcp-neo4j/servers/mcp-neo4j-cypher
uv run mcp-neo4j-cypher \
  --transport http \
  --server-host 127.0.0.1 \
  --server-port 8000 \
  --server-path /api/mcp/

2. Ensure Ollama is Running

Make sure you have Ollama installed and the model available:

ollama pull gpt-oss:120b-cloud
ollama serve

Usage

Option 1: Basic Client with Ollama

The simplest client that generates a single query:

# Run directly - uv handles everything
uv run mcp_neo4j_client.py

# Or use the installed command
uv run mcp-neo4j-client

What it does:

1. Fetches Neo4j schema from MCP server
2. Uses Ollama to generate a Cypher query for finding companies
3. Executes the query and displays results

Option 2: Interactive Agent with ReAct Pattern (Recommended)

An interactive agent that demonstrates the same pattern used in the backend:

# Run the interactive agent (uses Ollama gpt-oss:120b-cloud)
uv run interactive-agent

# Or run directly
uv run interactive_agent.py

# Use a different Ollama model
OLLAMA_MODEL=llama3.1 uv run interactive-agent

What it does:

1. Connects to MCP Neo4j server
2. Fetches the complete database schema
3. Creates a ReAct agent with schema-enhanced context
4. Enters an interactive loop where you can ask natural language questions
5. Translates your questions to Cypher queries using the schema
6. Executes queries and presents formatted results

Example queries you can try:

• "Show me all the node types in the database"
• "List all companies"
• "Find all relationships in the graph"
• "Show me the first 5 records of any type"

Features:

• ✅ Schema-aware query generation (uses exact property names)
• ✅ ReAct pattern for reasoning about queries
• ✅ Interactive chat loop for multiple queries
• ✅ Well-formatted markdown responses
• ✅ Same pattern as the production backend in databricks-neo4j-mcp-demo

Configuration

Create a .env file from the example:

cp .env.example .env

Environment variables:

• MCP_SERVER_URL: URL of the MCP server (default: http://localhost:8000/api/mcp/)
• OLLAMA_MODEL: Ollama model to use for interactive agent (default: gpt-oss:120b-cloud)

Managing Dependencies

Adding New Dependencies

# Add a new dependency
uv add package-name

# Add a development dependency
uv add --dev pytest

# Add with version constraint
uv add "package-name>=1.0.0"

Updating Dependencies

# Update all dependencies
uv sync --upgrade

# Update a specific package
uv sync --upgrade-package package-name

Lock File

The uv.lock file is automatically generated and should be committed to version control. It ensures reproducible builds across different environments.

Verification

To verify everything is set up correctly:

1. Check that the MCP server is running:

   curl http://localhost:8000/api/mcp/

2. Check that Ollama is running and has the model:

   ollama list | grep gpt-oss:120b-cloud

3. Run the client:

   uv run mcp_neo4j_client.py

Based On

This client is based on the examples from:

• /Users/ryanknight/projects/graphathon-snippets/examples/mcp/client
• MCP Python SDK streamable HTTP transport