Neo4j MCP Server

MCP server for Neo4j graph database operations.

Version: 0.2.0 Status: Internal Bodai integration component

Quick Links

• Overview
• Capabilities
• Quick Start
• MCP Server Configuration
• Tool Reference
• Configuration
• Development

Quality & CI

Crackerjack is the standard quality-control and CI/CD gate for Neo4j MCP changes. Local verification should mirror the Crackerjack workflow used across the Bodai ecosystem.

Overview

Neo4j MCP exposes graph database workflows through a FastMCP server. It gives agents a typed interface for Cypher execution, node and relationship management, path discovery, and schema inspection while preserving a narrow database client boundary.

Use this server when an agent needs to query or mutate graph data directly. Keep domain-specific graph policies in the calling system or a higher-level service layer rather than embedding them in generic Neo4j tools.

Capabilities

Implemented tool surface:

• Cypher execution: run parameterized Cypher queries
• Node management: create, retrieve, delete, and search nodes
• Relationship management: create and delete relationships between nodes
• Path discovery: find bounded paths between two nodes
• Schema inspection: retrieve labels, relationship types, indexes, and constraints
• Mock mode: exercise tool behavior without a live Neo4j connection
• HTTP health routes: /health and /healthz for MCP client and process supervision checks

Quick Start

Prerequisites

• Python 3.13+
• UV package manager
• Neo4j server for live access

Local Setup

git clone https://github.com/lesleslie/neo4j-mcp.git
cd neo4j-mcp
uv sync --group dev

Run In Mock Mode

export NEO4J_MCP_MOCK_MODE=true
uv run neo4j-mcp start
uv run neo4j-mcp health

Run With Neo4j

export NEO4J_MCP_URI="bolt://localhost:7687"
export NEO4J_MCP_USER="neo4j"
export NEO4J_MCP_PASSWORD="your-password"
export NEO4J_MCP_DATABASE="neo4j"
uv run neo4j-mcp start

The default HTTP bind is 127.0.0.1:3045.

CLI Commands

The CLI is built with mcp-common and provides the standard lifecycle command surface used by Bodai MCP servers.

uv run neo4j-mcp start      # Start the HTTP MCP server
uv run neo4j-mcp stop       # Stop the managed server process
uv run neo4j-mcp restart    # Restart the managed server process
uv run neo4j-mcp status     # Show process status
uv run neo4j-mcp health     # Run the local health probe

MCP Server Configuration

Claude / Codex Style Configuration

Add the server to an MCP client configuration:

{
  "mcpServers": {
    "neo4j": {
      "command": "uv",
      "args": ["run", "neo4j-mcp", "start"],
      "cwd": "<absolute-path-to-cloned-neo4j-mcp>",
      "env": {
        "NEO4J_MCP_URI": "bolt://localhost:7687",
        "NEO4J_MCP_USER": "neo4j",
        "NEO4J_MCP_PASSWORD": "your-password",
        "NEO4J_MCP_DATABASE": "neo4j"
      }
    }
  }
}

For tests or local client wiring, replace live connection values with NEO4J_MCP_MOCK_MODE=true.

Health Checks

curl http://127.0.0.1:3045/health
curl http://127.0.0.1:3045/healthz

Tool Reference

Tool responses follow a consistent ToolResponse shape:

{
  "success": true,
  "message": "Query returned 3 records",
  "data": {},
  "error": null,
  "next_steps": []
}

Configuration

Committed defaults live in settings/neo4j.yaml. Runtime overrides should come from environment variables or a local .env file that is not committed.

Project Structure

neo4j_mcp/
  __init__.py            # Package surface (__version__, model re-exports)
  __main__.py            # Module entry point (`python -m neo4j_mcp`)
  cli.py                 # mcp-common lifecycle CLI
  client.py              # Neo4j driver boundary
  config.py              # Pydantic settings and logging
  models.py              # Typed graph request and response models
  server.py              # FastMCP application factory
  tools/
    __init__.py          # Re-exports register_graph_tools
    graph_tools.py       # Registered MCP tools
settings/
  neo4j.yaml             # Committed defaults (documentation; see note below)
tests/

Note: settings/neo4j.yaml documents the operator-facing defaults but is not loaded by pydantic-settings at runtime — Neo4jSettings reads from the NEO4J_MCP_* environment variables and the .env file only. Use settings/neo4j.yaml as a reference when authoring your local .env.

Development

uv sync --group dev
uv run pytest
uv run ruff check neo4j_mcp tests
uv run ruff format neo4j_mcp tests
uv run mypy neo4j_mcp

Use targeted tests when isolating graph behavior:

uv run pytest tests -k graph -v

Security Notes

• Do not commit Neo4j passwords or connection strings containing credentials.
• Prefer parameterized Cypher through params when passing user-controlled values.
• Treat run_cypher as a privileged tool because it can mutate data.
• Use database permissions and separate users to constrain agent-accessible operations.