At a glance
- Availability: Experimental (how to enable).
- Auth: Basic auth.
- Connection: HTTP Basic auth with
NEO4J_USERNAMEas the username andNEO4J_PASSWORDas the password. - Docs: https://neo4j.com/docs/query-api/current/authentication-authorization/
Credentials
Set these per environment. See Connect an integration.| Variable | Required | Description |
|---|---|---|
NEO4J_USERNAME | Yes | Neo4j database username (Aura instances default to ‘neo4j’), used as the HTTP Basic username Docs. |
NEO4J_PASSWORD | Yes | Neo4j database password (shown once when an Aura instance is created), used as the HTTP Basic password Docs. |
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. |
Setup
- Create a Neo4j Aura instance: Sign up at 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.
- 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.
- Store credentials: Add NEO4J_USERNAME=neo4j and NEO4J_PASSWORD=… to your .env file. The Query API authenticates with HTTP Basic auth using these values.
- 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
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.