Neo4j

Neo4j

Graph database — nodes, relationships, Cypher queries. Prefer read-only Cypher over Neo4j's HTTP transactional API; use cypher-shell only when HTTP is not exposed.

How to call it

source "${XDG_CONFIG_HOME:-$HOME/.config}/lab-neo4j/config.env" 2>/dev/null || source ~/.lab/.env

: "${NEO4J_DB:=neo4j}"

# Prefer an explicit HTTP endpoint. If only the common bolt:// URL is present,
# derive the default HTTP URL for the same host.
if [ -z "${NEO4J_HTTP_URL:-}" ] && [ -n "${NEO4J_URL:-}" ]; then
  NEO4J_HTTP_URL="$(printf '%s\n' "$NEO4J_URL" | sed -E 's#^bolt(s)?://#http://#; s#:7687/?$#:7474#')"
fi

[ -n "${NEO4J_USER:-}" ] && [ -n "${NEO4J_PASSWORD:-}" ] && [ -n "${NEO4J_HTTP_URL:-}" ] || {
  echo "neo4j not configured - set NEO4J_USER, NEO4J_PASSWORD, and NEO4J_HTTP_URL (or NEO4J_URL)"
}

AUTH=(-u "$NEO4J_USER:$NEO4J_PASSWORD")

Auth is HTTP Basic. bolt:// URLs are for binary Bolt clients (cypher-shell, drivers); curl needs the HTTP listener. Never echo the password.

Configure neo4j_user, sensitive neo4j_password, optional neo4j_http_url/neo4j_url, and optional neo4j_db in Claude plugin settings or Gemini extension settings. The SessionStart/ConfigChange hook writes ${XDG_CONFIG_HOME:-~/.config}/lab-neo4j/config.env with mode 600. Use ~/.lab/.env only as a local migration fallback.

Running Cypher

All queries go through POST /db/<database>/tx/commit with a statements array:

cypher() {
  jq -n --arg stmt "$1" '{"statements":[{"statement":$stmt}]}' | \
  curl -sS "${AUTH[@]}" -H 'Content-Type: application/json' \
    "$NEO4J_HTTP_URL/db/$NEO4J_DB/tx/commit" \
    -d @-
}

Server discovery (available endpoints) is GET $NEO4J_HTTP_URL/. Multi-statement transactions are possible by passing several objects in the statements array, but do that only when the user explicitly asks.

Checking the response

The transactional API usually returns HTTP 200 even when Cypher failed. Inspect .errors before trusting .results:

cypher 'MATCH (n) RETURN n LIMIT 5' | jq '{errors, results}'

Any non-empty errors array means the query failed; report the code and message instead of treating the result as empty data.

Destructive actions

Any write Cypher (CREATE, MERGE, SET, DELETE, DROP, etc.) mutates the graph. Confirm with the user before running writes or multi-statement transactions that include them.

Configuration

NEO4J_USER, NEO4J_PASSWORD, NEO4J_DB, NEO4J_URL (bolt), and optionally NEO4J_HTTP_URL come from generated config, environment variables, or the legacy ~/.lab/.env fallback. Verify connectivity:

curl -sS "${AUTH[@]}" "$NEO4J_HTTP_URL/" -w '\nHTTP %{http_code}\n'

If only Bolt is exposed, use cypher-shell -a "$NEO4J_URL" -u "$NEO4J_USER" -p "$NEO4J_PASSWORD" instead of curl. Do not pass mutating Cypher this way unless the user explicitly confirmed the write.

When NOT to use this skill

• The user is asking about a different homelab service — load that service's skill instead.
• The user wants vector search — that's the qdrant skill.