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

# Neo4j connector

> Query and update Neo4j graph databases with Cypher from AgentRuntime workflow steps.

The **neo4j** MCP adapter connects over Bolt with a URI, username, password, and optional target database name. It provides read-only and write Cypher execution, schema introspection (`labels`, relationship types, property keys), and a connectivity ping. Use it for relationship analytics, knowledge graphs, recommendation pipelines, org-chart lookups, and graph-aware agents — often feeding tabular summaries into [Postgres](/connectors/postgres) or [MySQL](/connectors/mysql).

## Prerequisites

* A Neo4j database (self-hosted, Aura, or compatible) reachable over Bolt
* Bolt URI (`bolt://`, `bolt+s://`, `neo4j://`, or `neo4j+s://`)
* Database username and password with appropriate roles
* Optional target `Database` name for multi-database deployments (Neo4j 4+)
* **project\_contributor** access

## Connect in AgentRuntime

<Steps>
  <Step title="Create a connection">
    Go to **Connections** and click **New custom connection** to create a connection with your Neo4j Bolt credentials:

    * `URI` — e.g. `bolt+s://xxxx.databases.neo4j.io` (Aura) or `bolt://localhost:7687`
    * `Username` / `Password` — database authentication
    * `Database` — target database name (optional; defaults to `neo4j`)
  </Step>

  <Step title="Add neo4j MCP instance">
    Go to **MCP**, click **Add instance** for **neo4j**, wire your connection on **Instance config**, set the profile **active**, and save.
  </Step>

  <Step title="Test with a ping">
    Add a workflow with **mcp\_call** → `neo4j_ping`. Run it to confirm Bolt connectivity before Cypher queries.
  </Step>

  <Step title="Inspect graph schema (optional)">
    Run **mcp\_call** → `neo4j_schema` to list labels, relationship types, and property keys before building traversal queries.
  </Step>
</Steps>

See [Authentication](/integrations/authentication) for binding connections to MCP instances.

## What you can build

* **Recommendation engine** — `neo4j_query_read` traverse product → category → co-purchase paths → LLM ranks suggestions.
* **Org chart lookup** — `neo4j_query_read` on `(:Person)-[:REPORTS_TO*]->(:Person)` → answer manager-chain questions in Autopilot.
* **Graph enrichment** — External API data → `neo4j_execute_write` MERGE nodes and relationships from webhook payloads.
* **Schema-aware agents** — `neo4j_schema` list labels and relationship types → grounded Cypher generation with read-only queries.

## Tools

| Tool                  | Description                                                                       |
| --------------------- | --------------------------------------------------------------------------------- |
| `neo4j_query_read`    | Run a read-only Cypher query against Neo4j                                        |
| `neo4j_execute_write` | Run a write Cypher query against Neo4j                                            |
| `neo4j_schema`        | Return Neo4j labels, relationship types, and property keys from the graph catalog |
| `neo4j_ping`          | Verify Neo4j connectivity with a simple query                                     |

## Example

Find collaborators two hops away from a user:

```json theme={null}
{
  "id": "find-collaborators",
  "type": "mcp_call",
  "name": "Find nearby collaborators",
  "tool_name": "neo4j_query_read",
  "tool_args": {
    "cypher": "MATCH (u:User {id: $userId})-[:WORKED_WITH*1..2]-(other:User) RETURN DISTINCT other.name AS name, other.email AS email LIMIT 20",
    "parameters": {
      "userId": "{{input.user_id}}"
    },
    "max_records": 20
  },
  "timeout_s": 30
}
```

Reference graph results in a downstream step:

```
{{steps.find-collaborators.result.records}}
```

## Configuration

| Key              | Required | Default | Description                                                                   |
| ---------------- | -------- | ------- | ----------------------------------------------------------------------------- |
| `neo4j_uri`      | Yes      | —       | Bolt URI (e.g. `bolt://localhost:7687` or `neo4j+s://....databases.neo4j.io`) |
| `neo4j_username` | Yes      | —       | Neo4j database username for Bolt authentication                               |
| `neo4j_password` | Yes      | —       | Neo4j database password for Bolt authentication                               |
| `neo4j_database` | No       | `neo4j` | Target database name passed to the driver session                             |

## Troubleshooting

| Issue                  | Fix                                                                                              |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Bolt connection failed | Confirm URI scheme (`+s` for TLS), host, and port `7687`                                         |
| `Unauthorized`         | Verify username/password; reset credentials in Aura or self-hosted admin                         |
| Empty `records`        | Check label/property names with `neo4j_schema`; validate `$parameters` match Cypher placeholders |
| Results truncated      | Increase `max_records` (cap 10000) or add tighter `LIMIT` in Cypher                              |
| Write rejected         | Confirm the DB user has write privileges for `neo4j_execute_write` operations                    |

## Related

* [Integrations quickstart](/integrations/quickstart)
* [Postgres connector](/connectors/postgres) — relational store alongside graph analytics
* [MySQL connector](/connectors/mysql) — SQL reporting on tabular data linked to graph entities
* [Connector catalog](/integrations/connector-catalog)
* [Troubleshooting](/platform/troubleshooting)