Neo4j Cli Tools Skill

Neo4j CLI Tools skill

This skill provides comprehensive guidance on Neo4j command-line tools for database administration, query execution, cloud management, and AI agent integration.

When to Use

• Admin tasks: backup, restore, import, memory sizing → neo4j-admin
• Ad-hoc queries, scripting, CI/CD → cypher-shell
• Aura cloud provisioning → aura-cli
• MCP server install → neo4j-mcp

When NOT to Use

• Writing or optimizing Cypher queries → use neo4j-cypher-skill
• Upgrading Neo4j drivers or migrating Cypher syntax → use neo4j-migration-skill
• Starting a new Neo4j project from scratch → use neo4j-getting-started-skill

Available CLI Tools

1. neo4j-admin

Purpose: Comprehensive database administration tool

Categories:

• dbms - System-wide administration for single and clustered environments
• server - Server-level management tasks
• database - Database-specific operations (backup, restore, import, migrate)
• backup - Backup and restore operations

Common Use Cases:

• Database backup and restore
• Data import and export
• Server memory recommendations
• Initial password setup
• Database health checks

Reference: neo4j-admin-reference.md

2. cypher-shell

Purpose: Interactive command-line tool for executing Cypher queries

Key Features:

• Interactive REPL for ad-hoc queries
• Script execution from files
• Parameterized query support
• Multiple output formats (verbose, plain, auto)
• Remote database connections

Common Use Cases:

• Running Cypher queries from terminal
• Batch processing with query files
• Database exploration and debugging
• CI/CD pipeline integration
• Scripted data operations

Requirements: Java 21

Reference: cypher-shell-reference.md

3. aura-cli

Purpose: Command-line interface for managing Neo4j Aura cloud resources

Key Features:

• Instance provisioning and management
• Tenant administration
• Credential management
• Graph Analytics operations
• Customer-managed keys

Common Use Cases:

• Automating Aura instance creation
• Managing cloud database lifecycles
• CI/CD integration for cloud deployments
• Programmatic resource provisioning

Reference: aura-cli-reference.md

4. neo4j-mcp

Purpose: Model Context Protocol server for Neo4j integration with AI agents

For full installation and editor configuration guidance, use neo4j-mcp-skill — it covers all editors (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Kiro), stdio vs HTTP transport, and troubleshooting.

Quick install:

pip install neo4j-mcp-server
neo4j-mcp --version  # verify

Reference: neo4j-mcp-reference.md

Instructions

When a user asks about Neo4j CLI tools:

1. Identify the appropriate tool based on the use case:

• Administration tasks → neo4j-admin
• Query execution → cypher-shell
• Cloud management → aura-cli
• AI agent integration → neo4j-mcp

2. Check prerequisites:

• For cypher-shell: Verify Java 21 is installed
• For neo4j-mcp: Verify APOC plugin is available
• For aura-cli: Verify credentials are configured

3. Provide practical examples:

• Always include actual command syntax
• Show common parameter combinations
• Include environment variable alternatives
• Demonstrate error handling where relevant

4. Reference detailed documentation:

• Include the appropriate reference file from references/ directory
• Point to official Neo4j documentation for latest updates
• Mention version-specific considerations

5. Installation guidance:

• neo4j-admin and cypher-shell: Included with Neo4j installation
• aura-cli: Download from GitHub releases
• neo4j-mcp: Download binary from official repository
• Include installation verification steps

Backup and Recovery

Edition gate

Online backup requires Enterprise Edition. Community Edition users must use dump/load only (database must be offline).

Backup (Enterprise — database stays online)

# Full online backup — database stays online during backup
neo4j-admin database backup \
  --to-path=/backups/ \
  --database=neo4j \
  --compress

# Differential backup — only changes since last full backup (faster)
neo4j-admin database backup \
  --to-path=/backups/ \
  --database=neo4j \
  --type=DIFF \
  --compress

# Backup to cloud storage (S3, GCS, or HTTPS)
neo4j-admin database backup \
  --to-path=s3://my-bucket/neo4j-backups/ \
  --database=neo4j

Restore (Enterprise)

AGENT GATE — destructive operation: Before running restore, show the user the exact command and target database name, and wait for explicit confirmation. A restore overwrites the existing database.

# Restore from a full or differential backup
# Requires DB to be stopped, or use --force-offline for a running instance
neo4j-admin database restore \
  --from-path=/backups/neo4j-2026-01-15T10-00-00/ \
  --database=neo4j \
  --overwrite-destination=true

# Restore to a new database name (non-destructive path)
neo4j-admin database restore \
  --from-path=/backups/neo4j-2026-01-15T10-00-00/ \
  --database=neo4j-restored

Dump / Load (all editions — database must be offline)

Use for migrations, dev/test data transfers, and Community Edition backups.

# Dump — stop the database first, or pass --force-offline
neo4j-admin database dump --to-path=/exports/ neo4j

# Load — overwrites if target DB exists
neo4j-admin database load \
  --from-path=/exports/neo4j.dump \
  --database=neo4j \
  --overwrite-destination=true

AGENT GATE — destructive operation: Before running load with --overwrite-destination=true, confirm target database name and path with the user.

Key flags

Point-in-time restore strategy

• Full backup: weekly (e.g. every Sunday)
• Differential backup: daily (captures only changes since last full)
• Naming convention: include timestamp in path — e.g. /backups/neo4j-2026-01-19T02-00-00/
• Restore sequence: apply full backup first, then each differential in chronological order

# Example: restore Sunday full + Monday + Tuesday differentials
neo4j-admin database restore \
  --from-path=/backups/neo4j-2026-01-19T02-00-00/ \
  --database=neo4j --overwrite-destination=true

neo4j-admin database restore \
  --from-path=/backups/neo4j-2026-01-20T02-00-00/ \
  --database=neo4j --overwrite-destination=true

neo4j-admin database restore \
  --from-path=/backups/neo4j-2026-01-21T02-00-00/ \
  --database=neo4j --overwrite-destination=true

Reference: neo4j-admin-reference.md

---

Important Notes

• All commands support --help for detailed usage information
• Configuration priority: CLI flags > environment variables > config files
• Neo4j 2026.01 is the current version (as of documentation date)
• Always execute neo4j-admin commands as the Neo4j system user
• Exit code 0 indicates success; non-zero indicates errors

Environment Variables

Common environment variables across tools:

• NEO4J_URI / NEO4J_ADDRESS - Database connection URI
• NEO4J_USERNAME - Database username
• NEO4J_PASSWORD - Database password
• NEO4J_DATABASE - Target database name
• NEO4J_CONF - Path to neo4j.conf directory
• NEO4J_HOME - Neo4j installation directory

Resources

• Neo4j Operations Manual
• Cypher Shell Documentation
• Aura CLI GitHub
• Neo4j MCP Documentation
• Neo4j Developer Portal

---

Checklist

• [ ] Correct tool selected: neo4j-admin / cypher-shell / aura-cli / neo4j-mcp
• [ ] Credentials via env (NEO4J_USERNAME, NEO4J_PASSWORD); not hardcoded
• [ ] Destructive ops confirmed before execution
• [ ] Post-op verify: connect + SHOW INDEXES + count
• [ ] Backup taken before restore or schema change

neo4j-cli-tools-skill

Skill for database administration and automation using Neo4j command-line tools.

Covers:

• neo4j-admin — database management: backup/restore, imports (neo4j-admin database import), consistency checks, dump/load, user management, config tuning
• cypher-shell — interactive and scripted Cypher execution, --format, --param, piping queries from files, non-interactive mode for automation
• aura-cli — Aura instance management: create, pause, resume, delete, credential export, async status polling
• Neo4j MCP server setup — mcp-neo4j-cypher and mcp-neo4j-memory configuration for Claude Code, Cursor, and other MCP clients
• Common admin workflows: schema dump, user/role management, database copy, log inspection

Version / compatibility:

• neo4j-admin bundled with Neo4j 5.x / 2025.x
• aura-cli — install via pip install aura-cli
• cypher-shell — standalone download or bundled with Neo4j

Not covered:

• Cypher query authoring → neo4j-cypher-skill
• Aura provisioning via REST API → neo4j-aura-provisioning-skill
• Importing CSV/JSON data via Cypher → neo4j-import-skill

Install:

npx skills add https://github.com/neo4j-contrib/neo4j-skills --skill neo4j-cli-tools-skill

Or paste this link into your coding assistant: https://github.com/neo4j-contrib/neo4j-skills/tree/main/neo4j-cli-tools-skill

aura-cli Reference

Installation

Platform-Specific Installation

Windows:

move aura-cli.exe c:\windows\system32

macOS/Linux:

sudo mv aura-cli /usr/local/bin/
chmod +x /usr/local/bin/aura-cli

aura-cli --version

Initial Setup

1. Log in to Neo4j Console 2. Navigate to Account Settings 3. Generate API credentials (Client ID and Client Secret)

aura-cli credential add \
  --name "Aura API Credentials" \
  --client-id <your-client-id> \
  --client-secret <your-client-secret>

Basic Syntax

aura-cli [command] [subcommand] [flags]

Global Flags:

• -h, --help - Display help for any command
• -v, --version - Display version information
• --output {default,json,table} - Output format
• --auth-url <url> - Authentication URL (optional)
• --base-url <url> - API base URL (optional)

Command Categories

credential

aura-cli credential add \
  --name "Production Credentials" \
  --client-id <client-id> \
  --client-secret <client-secret>

aura-cli credential list

aura-cli credential use "Production Credentials"

aura-cli credential remove "Old Credentials"

instance

aura-cli instance create \
  --name "production-db" \
  --type "enterprise-db" \
  --region "us-east-1" \
  --memory "8GB" \
  --cloud-provider "gcp"

Options:

• --name - Instance name
• --type - Instance type (e.g., enterprise-db, professional-db)
• --region - Cloud region
• --memory - Memory allocation
• --cloud-provider - Cloud provider (gcp, aws, azure)
• --tenant-id - Tenant ID (if applicable)

Example Output:

{
  "id": "abc123def456",
  "name": "production-db",
  "status": "creating",
  "connection_url": "neo4j+s://abc123def456.databases.neo4j.io"
}

aura-cli instance list
aura-cli instance list --output table
aura-cli instance list --output json

aura-cli instance get <instance-id>
aura-cli instance get abc123def456 --output json

aura-cli instance update <instance-id> \
  --name "new-name" \
  --memory "16GB"

aura-cli instance pause <instance-id>

aura-cli instance resume <instance-id>

aura-cli instance delete <instance-id>
aura-cli instance delete abc123def456 --confirm

aura-cli instance overwrite <target-instance-id> \
  --source-instance-id <source-instance-id>

# List snapshots
aura-cli instance snapshot list <instance-id>

# Create snapshot
aura-cli instance snapshot create <instance-id> --name "backup-2026-02-16"

# Restore from snapshot
aura-cli instance snapshot restore <instance-id> --snapshot-id <snapshot-id>

tenant

aura-cli tenant list
aura-cli tenant get <tenant-id>

graph-analytics

aura-cli graph-analytics list
aura-cli graph-analytics get <instance-id>

customer-managed-key

aura-cli customer-managed-key list

aura-cli customer-managed-key add \
  --key-id <key-id> \
  --cloud-provider <provider>

Configuration

Config file location:

• Linux/macOS: ~/.aura-cli/config.json
• Windows: %USERPROFILE%\.aura-cli\config.json

Environment Variables:

• AURA_CLI_AUTH_URL - Override authentication URL
• AURA_CLI_BASE_URL - Override API base URL
• AURA_CLI_CLIENT_ID - Client ID for authentication
• AURA_CLI_CLIENT_SECRET - Client secret for authentication
• AURA_CLI_CONFIG_PATH - Custom config file location

Common Workflows

Provision New Instance

aura-cli credential add \
  --name "Aura Credentials" \
  --client-id $CLIENT_ID \
  --client-secret $CLIENT_SECRET

aura-cli instance create \
  --name "my-app-db" \
  --type "enterprise-db" \
  --region "us-east-1" \
  --memory "8GB" \
  --cloud-provider "aws"

aura-cli instance get <instance-id>

Backup and Restore

aura-cli instance snapshot create abc123def456 \
  --name "pre-migration-backup"

aura-cli instance snapshot list abc123def456

aura-cli instance snapshot restore abc123def456 \
  --snapshot-id snapshot-xyz789

Cost Management

aura-cli instance pause dev-instance-id
aura-cli instance resume dev-instance-id
aura-cli instance delete old-instance-id

CI/CD Integration

#!/bin/bash
INSTANCE_ID=$(aura-cli instance create \
  --name "test-$CI_BUILD_ID" \
  --type "professional-db" \
  --region "us-east-1" \
  --memory "4GB" \
  --output json | jq -r '.id')

echo "Created instance: $INSTANCE_ID"

# Run tests...

aura-cli instance delete $INSTANCE_ID

Multi-Environment Management

aura-cli credential use "Production Credentials"
aura-cli instance list

aura-cli credential use "Development Credentials"
aura-cli instance list

Refresh Staging from Production

aura-cli instance overwrite staging-instance-id \
  --source-instance-id production-instance-id

Output Examples

List Instances (Table)

aura-cli instance list --output table

+------------------+------------------+----------+----------+---------------+
| ID               | NAME             | TYPE     | STATUS   | REGION        |
+------------------+------------------+----------+----------+---------------+
| abc123def456     | production-db    | enterprise| running  | us-east-1     |
| xyz789ghi012     | staging-db       | professional| running| eu-west-1     |
| mno345pqr678     | dev-db           | free     | paused   | us-west-2     |
+------------------+------------------+----------+----------+---------------+

Get Instance (JSON)

aura-cli instance get abc123def456 --output json

{
  "id": "abc123def456",
  "name": "production-db",
  "type": "enterprise-db",
  "status": "running",
  "region": "us-east-1",
  "memory": "8GB",
  "cloud_provider": "aws",
  "connection_url": "neo4j+s://abc123def456.databases.neo4j.io",
  "created_at": "2026-01-15T10:30:00Z",
  "tenant_id": "tenant-123"
}

Scripting Examples

Bash: List All Instances

#!/bin/bash
set -e

aura-cli instance list --output json | jq -r '.[] | "\(.name) (\(.status)) - \(.connection_url)"'

Python: Create and Monitor Instance

import subprocess
import json
import time

def create_instance(name, memory="4GB"):
    cmd = [
        "aura-cli", "instance", "create",
        "--name", name,
        "--type", "professional-db",
        "--region", "us-east-1",
        "--memory", memory,
        "--output", "json"
    ]
    result = subprocess.run(cmd, capture_output=True, text=True)
    return json.loads(result.stdout)

def get_instance(instance_id):
    cmd = ["aura-cli", "instance", "get", instance_id, "--output", "json"]
    result = subprocess.run(cmd, capture_output=True, text=True)
    return json.loads(result.stdout)

instance = create_instance("test-db")
instance_id = instance["id"]
print(f"Created instance: {instance_id}")

while True:
    status = get_instance(instance_id)
    if status["status"] == "running":
        print(f"Instance ready: {status['connection_url']}")
        break
    print(f"Status: {status['status']}, waiting...")
    time.sleep(30)

Troubleshooting

Authentication Failed

Error: authentication failed

Verify credentials in Neo4j Console, then re-add:

aura-cli credential add --name "Aura Credentials" \
  --client-id <id> --client-secret <secret>

No Default Credential

Error: no default credential set

aura-cli credential use "Credential Name"

Instance Creation Failed

Error: instance creation failed - insufficient quota

Check account quota limits, billing status, and region availability in Neo4j Console.

API Rate Limiting

Error: rate limit exceeded

Add delays between API calls; use --output json and parse results to minimize calls.

Connection Issues

Error: unable to connect to Aura API

Check internet connectivity, corporate firewall/proxy settings, and API endpoint status: https://status.neo4j.io/

Best Practices

1. Secure Credentials: Never commit to version control; use environment variables in CI/CD 2. JSON Output for Scripts: Always use --output json in automation scripts 3. Pause Unused Instances: Reduce costs by pausing development/staging instances 4. Automate Backups: Schedule regular snapshots via cron/scheduled tasks 5. Error Handling: Check exit codes in scripts ($? in bash) 6. Multi-Credential Setup: Use separate credentials for different environments

Additional Resources

• Aura CLI GitHub Repository
• Aura CLI Releases
• Neo4j Aura Documentation
• Neo4j Console
• Aura API Documentation
• Neo4j Status Page

cypher-shell Reference

Installation

Cypher Shell is included with Neo4j installations in the bin/ directory.

Standalone:

# Visit https://neo4j.com/deployment-center/
# Download cypher-shell package for your platform

Homebrew (macOS):

brew install cypher-shell

cypher-shell --version

Requirements

• Java 21 (required)
• Network access to Neo4j instance (Bolt port, default 7687)

Basic Syntax

cypher-shell [OPTIONS] [cypher-statement]

Connection Options

cypher-shell -a neo4j://localhost:7687 -u neo4j -p password

• -a ADDRESS, --address ADDRESS, --uri ADDRESS
• Database URI (default: neo4j://localhost:7687)
• Environment variable: NEO4J_ADDRESS or NEO4J_URI

• -u USERNAME, --username USERNAME
• Environment variable: NEO4J_USERNAME

• -p PASSWORD, --password PASSWORD
• Environment variable: NEO4J_PASSWORD

• -d DATABASE, --database DATABASE
• Environment variable: NEO4J_DATABASE

• --encryption {true,false,default}
• default deduces from URI scheme (e.g., neo4j+ssc uses encryption)

• --impersonate IMPERSONATE
• User to impersonate

• --access-mode {read,write}
• Access mode (default: write)

Using Environment Variables

export NEO4J_URI=neo4j://localhost:7687
export NEO4J_USERNAME=neo4j
export NEO4J_PASSWORD=MySecurePassword
export NEO4J_DATABASE=mydb

cypher-shell

Interactive Mode

cypher-shell -a neo4j://localhost:7687 -u neo4j -p password

Connected to Neo4j 2026.01.3 at neo4j://localhost:7687
neo4j@neo4j>

Interactive Commands

• :help - Display available commands
• :exit - Exit the shell
• :param <name> => <value> - Set query parameter
• :params - List all parameters
• :begin - Start explicit transaction
• :commit - Commit current transaction
• :rollback - Rollback current transaction
• :source <file> - Execute statements from file
• :use <database> - Switch to different database
• :access-mode read|write - Switch access mode

Command History:

• Up/Down arrows navigate history
• History stored in ~/.neo4j/.cypher_shell_history
• Configure with --history option

Auto-completion (Neo4j 5+):

cypher-shell --enable-autocompletions

• Tab key triggers completions
• Completes Cypher keywords, functions, procedures

Multi-line Queries:

neo4j@neo4j> MATCH (n:Person)
... WHERE n.age > 25
... RETURN n.name, n.age;

Scripting Mode

cypher-shell -u neo4j -p password "MATCH (n) RETURN count(n);"

cypher-shell -u neo4j -p password -f queries.cypher

cat queries.cypher | cypher-shell -u neo4j -p password

echo "MATCH (n:Person) RETURN n.name LIMIT 5;" | cypher-shell -u neo4j -p password

Fail Fast (default — exits on first error):

cypher-shell -f script.cypher --fail-fast

Fail at End (continues and reports all errors):

cypher-shell -f script.cypher --fail-at-end

Output Formats

• --format auto - Tabular in interactive, plain in scripting (default)
• --format verbose - Tabular with statistics
• --format plain - Minimal formatting

cypher-shell --format verbose -u neo4j -p password "MATCH (n) RETURN n LIMIT 3;"

+---------------------------------------------+
| n                                           |
+---------------------------------------------+
| (:Person {name: "Alice", age: 30})         |
| (:Person {name: "Bob", age: 25})           |
| (:Person {name: "Charlie", age: 35})       |
+---------------------------------------------+
3 rows available after 45 ms, consumed after another 2 ms

cypher-shell --format plain -u neo4j -p password "MATCH (n:Person) RETURN n.name;"

"Alice"
"Bob"
"Charlie"

Output Options:

• --sample-rows SAMPLE-ROWS - Rows sampled for table width calculation (default: 1000; verbose only)
• --wrap {true,false} - Wrap column values if too narrow (default: true; verbose only)

Parameters

cypher-shell -P '{name: "Alice", minAge: 25}'

cypher-shell -P '{name: "Alice"}' -P '{minAge: 25}'

In Interactive Mode:

neo4j@neo4j> :param name => "Alice"
neo4j@neo4j> :param minAge => 25
neo4j@neo4j> :params
{
  "name": "Alice",
  "minAge": 25
}

Using Parameters in Queries:

MATCH (p:Person {name: $name})
WHERE p.age >= $minAge
RETURN p;

With Complex Types:

cypher-shell -P '{duration: duration({seconds: 3600})}'

Transaction Management

Each statement executes in its own implicit transaction by default.

Explicit Transactions (Interactive):

neo4j@neo4j> :begin
neo4j@neo4j# CREATE (n:Person {name: "Alice"});
neo4j@neo4j# CREATE (m:Person {name: "Bob"});
neo4j@neo4j# :commit

neo4j@neo4j> :begin
neo4j@neo4j# CREATE (n:Test);
neo4j@neo4j# :rollback

Advanced Options

cypher-shell --log /var/log/cypher-shell.log
cypher-shell --log  # Logs to stderr

cypher-shell --change-password  # Prompts for current and new passwords

cypher-shell --notifications  # Enable procedure and query notifications

cypher-shell --idle-timeout 30m  # Auto-close after inactivity

Idle timeout format: <hours>h<minutes>m<seconds>s (e.g., 1h, 1h30m, 30m)

cypher-shell --error-format {gql,legacy,stacktrace}

• gql - GQL standard format
• legacy - Traditional Neo4j format (default)
• stacktrace - Full stack traces

cypher-shell --non-interactive -f script.cypher  # Force non-interactive (useful on Windows)

Common Use Cases

Database Exploration

cypher-shell -u neo4j -p password "CALL db.labels();"

cypher-shell -u neo4j -p password "MATCH (n) RETURN labels(n)[0] AS label, count(n) AS count;"

cypher-shell -u neo4j -p password "CALL db.schema.visualization();"

Data Export

cypher-shell --format plain -u neo4j -p password \
  "MATCH (p:Person) RETURN p.name, p.age;" > people.csv

Batch Operations

cat << EOF > create_people.cypher
CREATE (:Person {name: "Alice", age: 30});
CREATE (:Person {name: "Bob", age: 25});
CREATE (:Person {name: "Charlie", age: 35});
EOF

cypher-shell -f create_people.cypher

CI/CD Integration

#!/bin/bash
if cypher-shell -u neo4j -p $NEO4J_PASSWORD "RETURN 1;" > /dev/null 2>&1; then
  echo "Database connection successful"
  exit 0
else
  echo "Database connection failed"
  exit 1
fi

Parameterized Queries

cypher-shell -P '{minAge: 30}' \
  "MATCH (p:Person) WHERE p.age >= \$minAge RETURN p.name, p.age;"

Read-Only Queries

cypher-shell --access-mode read -u neo4j -p password

Keyboard Shortcuts

Navigation:

• Ctrl+A - Move to beginning of line
• Ctrl+E - Move to end of line
• Ctrl+U - Clear line
• Ctrl+K - Delete from cursor to end
• Ctrl+C - Cancel current query

History:

• Up Arrow - Previous command
• Down Arrow - Next command
• Ctrl+R - Reverse search history

Completion:

• Tab - Trigger auto-completion (if enabled)

Environment Variables

• NEO4J_URI or NEO4J_ADDRESS - Connection URI
• NEO4J_USERNAME - Database username
• NEO4J_PASSWORD - Database password
• NEO4J_DATABASE - Target database name
• NEO4J_CYPHER_SHELL_HISTORY - History file path

Troubleshooting

Java Version Error

You are using an unsupported version of the Java runtime. Please use Java(TM) 21.

brew install openjdk@21
export JAVA_HOME=/path/to/java21

Connection Refused

Unable to connect to localhost:7687

1. Neo4j is running: neo4j status 2. Bolt port is correct (default 7687) 3. Firewall allows connection

Authentication Failed

The client is unauthorized due to authentication failure.

neo4j-admin dbms set-initial-password newpassword

SSL/TLS Errors

Connection failed with SSL error

cypher-shell --encryption false -a neo4j://localhost:7687

Best Practices

1. Use environment variables for credentials in scripts 2. Enable auto-completion for interactive work (Neo4j 5+) 3. Use parameters to prevent Cypher injection 4. Use explicit transactions for multi-statement operations 5. Use --fail-at-end for data migration scripts 6. Verify Java 21 before deployment

Additional Resources

• Cypher Shell Documentation
• Cypher Query Language Reference
• Bolt Protocol Specification
• Neo4j Deployment Center

neo4j-admin Reference

neo4j-admin is installed automatically with Neo4j in the bin/ directory.

neo4j-admin --version

Basic Syntax

neo4j-admin [OPTIONS] [COMMAND]

Global Options:

• --help, -h - Show help message
• --version, -V - Print version information
• --verbose - Print additional information
• --expand-commands - Allow command expansion in config value evaluation

Command Categories

dbms

set-default-admin

neo4j-admin dbms set-default-admin <username>

set-initial-password

neo4j-admin dbms set-initial-password <password>

neo4j-admin dbms set-initial-password MySecureP@ssw0rd

unbind-system-db

Removes cluster state to enable rebinding to a different cluster.

neo4j-admin dbms unbind-system-db

server

memory-recommendation

neo4j-admin server memory-recommendation

# Recommended memory settings:
server.memory.heap.initial_size=4g
server.memory.heap.max_size=4g
server.memory.pagecache.size=8g

report

Generates a diagnostic archive for Neo4j support team.

neo4j-admin server report

Options:

• --to=<path> - Output directory for the report archive
• --list - List available classifiers
• --filter=<classifier> - Filter specific data to include

license

neo4j-admin server license --accept-commercial
neo4j-admin server license --accept-evaluation

database

backup

neo4j-admin database backup <database-name> --to-path=<backup-directory>

neo4j-admin database backup neo4j --to-path=/backups/$(date +%Y%m%d)

Options:

• --to-path=<path> - Destination directory (required)
• --type=<type> - Backup type: full or differential
• --keep-failed - Keep failed backup attempts
• --verbose - Print detailed progress

restore

Important: Database must be stopped before restore.

neo4j-admin database restore <database-name> --from-path=<backup-directory>

neo4j-admin database restore neo4j --from-path=/backups/20260216

dump

neo4j-admin database dump <database-name> --to-path=<dump-file>

neo4j-admin database dump mydb --to-path=/exports/mydb.dump

load

neo4j-admin database load <database-name> --from-path=<dump-file>

neo4j-admin database load newdb --from-path=/exports/mydb.dump --overwrite-destination=true

Options:

• --from-path=<path> - Source dump file (required)
• --overwrite-destination - Allow overwriting existing database

import

neo4j-admin database import \
  --nodes=<node-files> \
  --relationships=<relationship-files> \
  --database=<database-name>

neo4j-admin database import \
  --nodes=Person=persons.csv \
  --relationships=KNOWS=knows.csv \
  --database=socialnetwork \
  --delimiter=","

Options:

• --nodes=<Label>=<file> - Node CSV files with optional labels
• --relationships=<TYPE>=<file> - Relationship CSV files with types
• --delimiter=<char> - CSV field delimiter (default: comma)
• --array-delimiter=<char> - Array value delimiter (default: semicolon)
• --skip-duplicate-nodes - Skip duplicate node IDs
• --skip-bad-relationships - Skip relationships with invalid nodes

check

neo4j-admin database check <database-name>

neo4j-admin database check neo4j --verbose

Options:

• --report-dir=<path> - Directory for consistency report
• --verbose - Detailed output

copy

neo4j-admin database copy <source-db> <target-db>

neo4j-admin database copy production staging

migrate

neo4j-admin database migrate <database-name>

neo4j-admin database migrate legacydb --force-btree-indexes-to-range

backup (legacy)

neo4j-admin backup --backup-dir=<path> --database=<name>

Configuration

Commands resolve settings in this order (highest to lowest priority): 1. --additional-config flag 2. Command-specific configuration files 3. neo4j-admin.conf 4. neo4j.conf

neo4j-admin database backup mydb --to-path=/backups @/path/to/options.conf

Example options.conf:

--verbose
--keep-failed=true

Environment Variables

• NEO4J_CONF - Path to directory containing neo4j.conf
• NEO4J_DEBUG - Enable debug output (set to any value)
• NEO4J_HOME - Neo4j installation directory
• HEAP_SIZE - JVM maximum heap size (e.g., 512m, 4g)
• JAVA_OPTS - Custom JVM settings (takes precedence over HEAP_SIZE)

Common Workflows

Initial Setup

neo4j-admin dbms set-initial-password MySecurePassword
neo4j-admin server memory-recommendation

Backup and Restore

neo4j-admin database backup neo4j --to-path=/backups/full
neo4j-admin database backup neo4j --to-path=/backups/diff --type=differential

neo4j stop
neo4j-admin database restore neo4j --from-path=/backups/full
neo4j start

Data Migration

neo4j-admin database dump production --to-path=/exports/prod.dump
neo4j-admin database load production-copy --from-path=/exports/prod.dump
neo4j-admin database check production-copy

CSV Import

neo4j-admin database import \
  --nodes=User=users.csv \
  --nodes=Product=products.csv \
  --relationships=PURCHASED=purchases.csv \
  --database=ecommerce \
  --skip-bad-relationships

Exit Codes

• 0 - Success
• Non-zero - Error occurred (check error message for details)

Best Practices

1. Always run as Neo4j user: Execute as the system user that owns the Neo4j installation 2. Stop database for restore: Always stop before running restore operations 3. Verify backups: Use check command to verify backup integrity 4. Use full paths: Specify absolute paths for backup and dump locations 5. Test in non-production: Test migration and import commands in development first 6. Monitor disk space: Ensure sufficient disk space for backups and dumps 7. Automate backups: Schedule regular backups using cron or system schedulers

Troubleshooting

Permission Denied

sudo -u neo4j neo4j-admin database backup mydb --to-path=/backups

Database Must Be Stopped

neo4j stop
neo4j-admin database restore mydb --from-path=/backup
neo4j start

Insufficient Memory

HEAP_SIZE=4g neo4j-admin database import --nodes=large.csv --database=bigdb

Configuration Not Found

NEO4J_CONF=/path/to/conf neo4j-admin database backup mydb --to-path=/backup

Additional Resources

• Neo4j Operations Manual - neo4j-admin
• Database Backup Documentation
• CSV Import Guide
• Configuration Reference

neo4j-mcp Reference

Installation

Download binary from github.com/neo4j/mcp:

# macOS/Linux
curl -L https://github.com/neo4j/mcp/releases/latest/download/neo4j-mcp-<platform> -o neo4j-mcp
chmod +x neo4j-mcp
sudo mv neo4j-mcp /usr/local/bin/

# Verify installation
neo4j-mcp --version

Requires: APOC plugin, network access to Neo4j.

Configuration Options

Connection Settings (Required)

Neo4j URI:

neo4j-mcp --neo4j-uri bolt://localhost:7687
# or
export NEO4J_URI=bolt://localhost:7687
neo4j-mcp

Username:

neo4j-mcp --neo4j-username neo4j
# or
export NEO4J_USERNAME=neo4j
neo4j-mcp

Password:

neo4j-mcp --neo4j-password password
# or
export NEO4J_PASSWORD=password
neo4j-mcp

Database Name (optional):

neo4j-mcp --neo4j-database mydb
# or
export NEO4J_DATABASE=mydb  # default: neo4j
neo4j-mcp

Operational Settings (Optional)

Read-Only Mode:

neo4j-mcp --neo4j-read-only true
# or
export NEO4J_READ_ONLY=true
neo4j-mcp

Disables write tools when enabled.

Telemetry:

neo4j-mcp --neo4j-telemetry false
# or
export NEO4J_TELEMETRY=false  # default: true
neo4j-mcp

Schema Sample Size:

neo4j-mcp --neo4j-schema-sample-size 200
# or
export NEO4J_SCHEMA_SAMPLE_SIZE=200  # default: 100
neo4j-mcp

Number of nodes to sample for schema inference.

Transport Modes

STDIO Mode (default):

neo4j-mcp --neo4j-transport-mode stdio
# or
export NEO4J_TRANSPORT_MODE=stdio
neo4j-mcp

Used for direct integration with AI agents.

HTTP Mode:

neo4j-mcp --neo4j-transport-mode http \
  --neo4j-http-port 8080 \
  --neo4j-http-host 0.0.0.0
# or
export NEO4J_TRANSPORT_MODE=http
export NEO4J_MCP_HTTP_PORT=8080
export NEO4J_MCP_HTTP_HOST=0.0.0.0
neo4j-mcp

Used for remote access via HTTP.

HTTP-Specific Settings

Port Configuration:

neo4j-mcp --neo4j-http-port 8443
# or
export NEO4J_MCP_HTTP_PORT=8443  # default: 443 (TLS) or 80 (no TLS)

Host Binding:

neo4j-mcp --neo4j-http-host 127.0.0.1
# or
export NEO4J_MCP_HTTP_HOST=127.0.0.1  # default: 127.0.0.1

CORS Origins:

neo4j-mcp --neo4j-http-allowed-origins "https://example.com,https://app.example.com"
# or
export NEO4J_MCP_HTTP_ALLOWED_ORIGINS="https://example.com,https://app.example.com"

TLS/HTTPS:

neo4j-mcp --neo4j-http-tls-enabled true \
  --neo4j-http-tls-cert-file /path/to/cert.pem \
  --neo4j-http-tls-key-file /path/to/key.pem
# or
export NEO4J_MCP_HTTP_TLS_ENABLED=true
export NEO4J_MCP_HTTP_TLS_CERT_FILE=/path/to/cert.pem
export NEO4J_MCP_HTTP_TLS_KEY_FILE=/path/to/key.pem

Authentication Header:

neo4j-mcp --neo4j-http-auth-header-name X-API-Key
# or
export NEO4J_HTTP_AUTH_HEADER_NAME=X-API-Key  # default: Authorization

Environment Variables Reference

Required

• NEO4J_URI - Database connection URI
• NEO4J_USERNAME - Database username
• NEO4J_PASSWORD - Database password

Optional

• NEO4J_DATABASE - Database name (default: neo4j)
• NEO4J_READ_ONLY - Enable read-only mode (default: false)
• NEO4J_TELEMETRY - Enable telemetry (default: true)
• NEO4J_SCHEMA_SAMPLE_SIZE - Schema sampling size (default: 100)
• NEO4J_TRANSPORT_MODE - Transport mode: stdio or http (default: stdio)

HTTP Transport (when NEO4J_TRANSPORT_MODE=http)

• NEO4J_MCP_HTTP_PORT - HTTP server port (default: 443 with TLS, 80 without)
• NEO4J_MCP_HTTP_HOST - HTTP server host (default: 127.0.0.1)
• NEO4J_MCP_HTTP_ALLOWED_ORIGINS - CORS origins (comma-separated)
• NEO4J_MCP_HTTP_TLS_ENABLED - Enable TLS (default: false)
• NEO4J_MCP_HTTP_TLS_CERT_FILE - TLS certificate file path
• NEO4J_MCP_HTTP_TLS_KEY_FILE - TLS private key file path
• NEO4J_HTTP_AUTH_HEADER_NAME - Auth header name (default: Authorization)

Deprecated

• NEO4J_MCP_TRANSPORT - Use NEO4J_TRANSPORT_MODE instead

Common Use Cases

Local Development with Claude Desktop

Configuration for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "neo4j": {
      "command": "neo4j-mcp",
      "env": {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password",
        "NEO4J_DATABASE": "neo4j"
      }
    }
  }
}

Read-Only Access

NEO4J_URI=bolt://localhost:7687 \
NEO4J_USERNAME=neo4j \
NEO4J_PASSWORD=password \
NEO4J_READ_ONLY=true \
neo4j-mcp

Use Case: Provide safe access to production databases for AI analysis.

Neo4j Aura Integration

NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io \
NEO4J_USERNAME=neo4j \
NEO4J_PASSWORD=your-aura-password \
NEO4J_DATABASE=neo4j \
neo4j-mcp

HTTP Server Mode

NEO4J_URI=bolt://localhost:7687 \
NEO4J_USERNAME=neo4j \
NEO4J_PASSWORD=password \
NEO4J_TRANSPORT_MODE=http \
NEO4J_MCP_HTTP_PORT=8080 \
NEO4J_MCP_HTTP_HOST=0.0.0.0 \
neo4j-mcp

Use Case: Remote access from web applications or multiple clients.

Secure HTTP with TLS

NEO4J_URI=bolt://localhost:7687 \
NEO4J_USERNAME=neo4j \
NEO4J_PASSWORD=password \
NEO4J_TRANSPORT_MODE=http \
NEO4J_MCP_HTTP_PORT=8443 \
NEO4J_MCP_HTTP_TLS_ENABLED=true \
NEO4J_MCP_HTTP_TLS_CERT_FILE=/path/to/cert.pem \
NEO4J_MCP_HTTP_TLS_KEY_FILE=/path/to/key.pem \
neo4j-mcp

Docker Deployment

docker run -d \
  --name neo4j-mcp \
  -e NEO4J_URI=bolt://neo4j:7687 \
  -e NEO4J_USERNAME=neo4j \
  -e NEO4J_PASSWORD=password \
  -e NEO4J_TRANSPORT_MODE=http \
  -e NEO4J_MCP_HTTP_PORT=8080 \
  -e NEO4J_MCP_HTTP_HOST=0.0.0.0 \
  -p 8080:8080 \
  neo4j/mcp:latest

MCP Capabilities

Tools

AI agents can execute Neo4j operations through tools:

• Query Execution: Run Cypher queries
• Schema Inspection: Get graph schema information
• Node Operations: Create, read, update, delete nodes
• Relationship Operations: Manage relationships
• Graph Algorithms: Execute graph algorithms (via APOC)

Example Tool Usage (conceptual):

Agent: "Show me the database schema"
MCP Tool: schema_inspection()
Result: Returns node labels, relationships, properties

Resources

Read-only access to database context:

• Database Schema: Current graph schema
• Statistics: Node/relationship counts
• Constraints: Defined constraints and indexes
• Procedures: Available APOC procedures

Prompts

Pre-defined templates for common operations:

• Natural language to Cypher translation
• Schema exploration queries
• Common graph patterns
• Data analysis templates

Integration Examples

Claude Code Integration

Add to your project's .claude/mcp_servers.json:

{
  "neo4j": {
    "command": "/usr/local/bin/neo4j-mcp",
    "env": {
      "NEO4J_URI": "bolt://localhost:7687",
      "NEO4J_USERNAME": "neo4j",
      "NEO4J_PASSWORD": "password"
    }
  }
}

Python Script Integration

import subprocess
import json

def start_neo4j_mcp():
    env = {
        "NEO4J_URI": "bolt://localhost:7687",
        "NEO4J_USERNAME": "neo4j",
        "NEO4J_PASSWORD": "password"
    }

    process = subprocess.Popen(
        ["neo4j-mcp"],
        env=env,
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE
    )

    return process

# Start MCP server
mcp_server = start_neo4j_mcp()

Node.js Integration

const { spawn } = require('child_process');

const neo4jMcp = spawn('neo4j-mcp', [], {
  env: {
    NEO4J_URI: 'bolt://localhost:7687',
    NEO4J_USERNAME: 'neo4j',
    NEO4J_PASSWORD: 'password',
    NEO4J_TRANSPORT_MODE: 'stdio'
  }
});

neo4jMcp.stdout.on('data', (data) => {
  console.log(`MCP: ${data}`);
});

Best Practices

Security

1. Use Read-Only Mode for production analysis 2. Secure Credentials: Use environment variables, never hardcode 3. Enable TLS for HTTP transport in production 4. Restrict CORS Origins to trusted domains only 5. Use Strong Passwords: Follow Neo4j security best practices 6. Network Isolation: Run MCP server in secure network segments

Performance

1. Adjust Schema Sample Size: Balance between accuracy and performance 2. Use APOC Procedures: Leverage APOC for complex operations 3. Connection Pooling: Let the MCP server manage connections 4. Monitor Resources: Track memory and CPU usage

Operational

1. Enable Telemetry: Help improve the MCP server (or disable for privacy) 2. Log Management: Capture stdout/stderr for debugging 3. Health Checks: Implement monitoring for MCP server availability 4. Version Control: Document neo4j-mcp version in deployments 5. Test Connections: Verify Neo4j connectivity before starting MCP

Development

1. Use STDIO Locally: Simplest for desktop AI agent integration 2. Use HTTP for Remote: Better for web applications 3. Test in Read-Only: Develop queries safely before enabling writes 4. Schema Exploration: Start with schema inspection before complex queries

Troubleshooting

Connection Refused

Error: Unable to connect to Neo4j

Check: 1. Neo4j is running: neo4j status 2. URI is correct (protocol, host, port) 3. Firewall allows connection 4. Credentials are valid

APOC Not Available

Warning: APOC procedures not found

Solution: Install APOC plugin:

# For Neo4j installations
# Add to neo4j.conf:
dbms.security.procedures.unrestricted=apoc.*

# Download APOC jar to plugins directory
# Restart Neo4j

Authentication Failed

Error: Authentication failed

Solution: 1. Verify credentials 2. Check user has appropriate permissions 3. Verify database name is correct

Port Already in Use (HTTP mode)

Error: Address already in use

Solution:

# Use different port
neo4j-mcp --neo4j-transport-mode http --neo4j-http-port 8081

TLS Certificate Errors

Error: Invalid TLS certificate

Check: 1. Certificate file path is correct 2. Certificate matches key file 3. Certificate is not expired 4. Certificate permissions are readable

Monitoring and Logging

Capture Logs

# Redirect to log file
neo4j-mcp 2>&1 | tee neo4j-mcp.log

Systemd Service (Linux)

[Unit]
Description=Neo4j MCP Server
After=network.target neo4j.service

[Service]
Type=simple
User=neo4j
Environment="NEO4J_URI=bolt://localhost:7687"
Environment="NEO4J_USERNAME=neo4j"
Environment="NEO4J_PASSWORD=password"
ExecStart=/usr/local/bin/neo4j-mcp
Restart=on-failure

[Install]
WantedBy=multi-user.target

Health Check Script

#!/bin/bash
# health-check.sh

if curl -f http://localhost:8080/health > /dev/null 2>&1; then
    echo "neo4j-mcp is healthy"
    exit 0
else
    echo "neo4j-mcp is unhealthy"
    exit 1
fi

Example AI Agent Interactions

Schema Exploration

User: "What's in this database?"

Agent via MCP:

• Calls schema_inspection tool
• Returns: Labels, relationships, properties
• Presents summary to user

Natural Language Query

User: "Show me all people over 30"

Agent via MCP:

• Converts to Cypher: MATCH (p:Person) WHERE p.age > 30 RETURN p
• Executes via query_execution tool
• Formats results for user

Data Analysis

User: "Find the most connected person"

Agent via MCP:

• Uses graph algorithms
• Executes: MATCH (p:Person)-[r]->() RETURN p.name, count(r) ORDER BY count(r) DESC LIMIT 1
• Provides insights

Additional Resources

• Neo4j MCP Official Documentation
• Neo4j MCP GitHub Repository
• Model Context Protocol Specification
• Neo4j Developer Guides - MCP
• Getting Started with MCP Servers Blog
• Neo4j APOC Documentation