Neo4j Pet

Connect to Neo4j graph databases to run Cypher queries, manage nodes and relationships, explore schemas, and find paths between entities.

Quick Start

1. Set Up Environment Variables

Create a .env file in your project root:

# Neo4j Connection (required)
NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password

# Optional
NEO4J_DATABASE=neo4j

2. Connection Examples

Local Neo4j Desktop:

NEO4J_URI=bolt://localhost:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_local_password

Neo4j Aura (Cloud):

NEO4J_URI=neo4j+s://xxxxx.databases.neo4j.io
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_aura_password

Self-hosted with TLS:

NEO4J_URI=bolt+s://your-server.com:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_password

3. Test Connection

opencode run "test neo4j connection"

Available Tools

| Tool | Description | Read-Only | |------|-------------|-----------| | neo4j-test-connection | Test database connection and return server info | ✅ | | neo4j-get-schema | Get node labels, relationship types, property keys | ✅ | | neo4j-run-cypher | Execute read-only Cypher queries | ✅ | | neo4j-write-cypher | Execute Cypher queries that modify data | ❌ | | neo4j-list-nodes | List nodes with optional label and property filters | ✅ | | neo4j-get-node | Get a specific node by ID or properties | ✅ | | neo4j-create-node | Create a new node with labels and properties | ❌ | | neo4j-create-relationship | Create a relationship between nodes | ❌ | | neo4j-update-node | Update properties on a node | ❌ | | neo4j-delete-node | Delete a node (optionally with relationships) | ❌ | | neo4j-find-path | Find shortest path between two nodes | ✅ | | neo4j-get-statistics | Get database statistics and counts | ✅ |

Usage Examples

Explore the Database

# Get schema overview
opencode run "get the neo4j database schema"

# Get statistics
opencode run "get neo4j database statistics"

# List all nodes
opencode run "list all nodes in neo4j"

Query Data

# List nodes by label
opencode run "list all Person nodes in neo4j"

# Run custom Cypher
opencode run "run cypher MATCH (p:Person)-[:KNOWS]->(friend) RETURN p.name, friend.name LIMIT 10"

# Find a specific node
opencode run "get the Person node with email [email protected]"

Modify Data

# Create a node
opencode run "create a Person node with name Alice and age 30"

# Create a relationship
opencode run "create a KNOWS relationship from node 5 to node 10"

# Update a node
opencode run "update node 5 to set status to active"

# Delete a node
opencode run "delete node 15 and all its relationships"

Graph Traversal

# Find path between nodes
opencode run "find the shortest path between node 1 and node 50"

# Find path with specific relationship types
opencode run "find path from node 1 to node 50 using only KNOWS and WORKS_WITH relationships"

Read-Only Mode

Enable read-only mode to prevent accidental data modifications:

# Via environment variable
export NEO4J_READ_ONLY=true

# Via pets CLI
pets read-only neo4j on

# Check status
pets read-only --status

In read-only mode, only these tools are available:

• neo4j-test-connection
• neo4j-get-schema
• neo4j-run-cypher
• neo4j-list-nodes
• neo4j-get-node
• neo4j-find-path
• neo4j-get-statistics

Parameterized Queries

Always use parameterized queries for safety and performance:

# Instead of string concatenation
opencode run "run cypher MATCH (n:Person {name: \$name}) RETURN n with params {\"name\": \"Alice\"}"

The paramsJson field accepts a JSON string with parameter values.

Cypher Quick Reference

-- Find all nodes
MATCH (n) RETURN n LIMIT 100

-- Find nodes by label
MATCH (p:Person) RETURN p

-- Find by property
MATCH (p:Person {name: 'Alice'}) RETURN p

-- Find relationships
MATCH (p:Person)-[r:KNOWS]->(friend) RETURN p, r, friend

-- Create node
CREATE (p:Person {name: 'Bob', age: 25}) RETURN p

-- Create relationship
MATCH (a:Person {name: 'Alice'}), (b:Person {name: 'Bob'})
CREATE (a)-[:KNOWS {since: 2020}]->(b)

-- Update properties
MATCH (p:Person {name: 'Alice'}) SET p.age = 31 RETURN p

-- Delete node
MATCH (p:Person {name: 'Old'}) DETACH DELETE p

-- Shortest path
MATCH path = shortestPath((a:Person {name: 'Alice'})-[*]-(b:Person {name: 'Bob'}))
RETURN path

Troubleshooting

Connection refused

• Ensure Neo4j is running
• Check the URI protocol (bolt:// for local, neo4j+s:// for Aura)
• Verify firewall allows the port (default: 7687)

Authentication failed

• Double-check username and password
• For Aura, use the credentials from your instance dashboard
• Ensure the user has appropriate permissions

Database not found

• Check NEO4J_DATABASE is set correctly
• Default database is usually neo4j
• For Aura, the database name is shown in your instance settings

Permission denied

• Some operations require admin privileges
• Check user roles in Neo4j
• Consider using read-only mode for safer queries

Resources

• Neo4j Documentation
• Cypher Manual
• Neo4j Aura
• Neo4j Desktop