> ## Documentation Index
> Fetch the complete documentation index at: https://veryfront.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Neo4j

> Run Cypher queries against a Neo4j Aura or self-hosted graph database via the Query API for graph data and GraphRAG workloads

## At a glance

* **Availability**: Experimental ([how to enable](/cloud/integrations)).
* **Auth**: Basic auth.
* **Connection**: HTTP Basic auth with `NEO4J_USERNAME` as the username and `NEO4J_PASSWORD` as the password.
* **Docs**: [https://neo4j.com/docs/query-api/current/authentication-authorization/](https://neo4j.com/docs/query-api/current/authentication-authorization/)

## Credentials

Set these per environment. See [Connect an integration](/cloud/integrations).

| Variable         | Required | Description                                                                                                                                                                                                     |
| ---------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NEO4J_USERNAME` | Yes      | Neo4j database username (Aura instances default to 'neo4j'), used as the HTTP Basic username [Docs](https://neo4j.com/docs/query-api/current/authentication-authorization/).                                    |
| `NEO4J_PASSWORD` | Yes      | Neo4j database password (shown once when an Aura instance is created), used as the HTTP Basic password [Docs](https://neo4j.com/docs/query-api/current/authentication-authorization/).                          |
| `NEO4J_HOST`     | No       | Neo4j host serving the Query API, e.g. xxxxxxxx.databases.neo4j.io for Aura or your-server:7474 for self-hosted - pass it as the host parameter of each tool [Docs](https://neo4j.com/docs/query-api/current/). |

## Setup

1. **Create a Neo4j Aura instance**: Sign up at [https://console.neo4j.io](https://console.neo4j.io) and create an AuraDB Free instance (no credit card required). Download or copy the generated password - it is shown only once. Self-hosted Neo4j 5.19+ also exposes the Query API.
2. **Find your host**: From the Aura console, copy the instance's connection URI (neo4j+s\://xxxxxxxx.databases.neo4j.io). The host part (xxxxxxxx.databases.neo4j.io) is what tools take as the host parameter; store it in NEO4J\_HOST for reference.
3. **Store credentials**: Add NEO4J\_USERNAME=neo4j and NEO4J\_PASSWORD=.... to your .env file. The Query API authenticates with HTTP Basic auth using these values.
4. **Verify access**: Run the Run Cypher Query tool with statement 'RETURN 1 AS ok' against database 'neo4j'. A 401 means wrong credentials; a connection error usually means the wrong host.

* The Query API requires Neo4j 5.19+ (all Aura instances qualify); on self-managed instances below 5.25 it is disabled by default and must be enabled in the server configuration. Aura serves it over HTTPS on port 443
* Self-hosted instances must expose HTTPS (port 7473 by default) for these tools, since tool URLs use https\:// - include the port in the host parameter, e.g. my-server:7473
* Always pass Cypher values via the parameters object (\$placeholders) rather than string-concatenating them into the statement - this enables plan caching and prevents Cypher injection
* Both tools run implicit (auto-commit) transactions; explicit multi-request transactions are not exposed
* The Query API has no server-side read-only mode: Run Cypher Query is read-only by convention only, and write statements sent through it would execute. Connect with a read-only database user if you need a hard guarantee

Provider API reference: [https://neo4j.com/docs/query-api/current/](https://neo4j.com/docs/query-api/current/)

## Tools

| Tool             | Access | Description                                                                                                                                                                                                                                                                                                                  |
| ---------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Run Cypher Query | Read   | Execute a read-only Cypher query (MATCH .... RETURN) in an implicit transaction and get back fields and result rows - use for lookups, traversals, and GraphRAG retrieval. Note: the Query API does not enforce read-only access, so only submit read statements here (use a read-only database user to guarantee no writes) |
| Run Cypher Write | Write  | Execute a Cypher statement that modifies the graph (CREATE, MERGE, SET, DELETE) in an implicit transaction                                                                                                                                                                                                                   |

## Example prompts

* Query my Neo4j database to show the node labels, relationship types, and a few sample nodes so I understand the graph model.
* Answer my question by writing and running a parameterized Cypher query against my Neo4j database, then explain the result.