Skip to main content
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 or 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

1

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)
2

Add neo4j MCP instance

Go to MCP, click Add instance for neo4j, wire your connection on Instance config, set the profile active, and save.
3

Test with a ping

Add a workflow with mcp_call → neo4j_ping. Run it to confirm Bolt connectivity before Cypher queries.
4

Inspect graph schema (optional)

Run mcp_call → neo4j_schema to list labels, relationship types, and property keys before building traversal queries.
See 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

ToolDescription
neo4j_query_readRun a read-only Cypher query against Neo4j
neo4j_execute_writeRun a write Cypher query against Neo4j
neo4j_schemaReturn Neo4j labels, relationship types, and property keys from the graph catalog
neo4j_pingVerify Neo4j connectivity with a simple query

​
Example

Find collaborators two hops away from a user: 
{
  "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

KeyRequiredDefaultDescription
neo4j_uriYes—Bolt URI (e.g. bolt://localhost:7687 or neo4j+s://....databases.neo4j.io)
neo4j_usernameYes—Neo4j database username for Bolt authentication
neo4j_passwordYes—Neo4j database password for Bolt authentication
neo4j_databaseNoneo4jTarget database name passed to the driver session

​
Troubleshooting

IssueFix
Bolt connection failedConfirm URI scheme (+s for TLS), host, and port 7687
UnauthorizedVerify username/password; reset credentials in Aura or self-hosted admin
Empty recordsCheck label/property names with neo4j_schema; validate $parameters match Cypher placeholders
Results truncatedIncrease max_records (cap 10000) or add tighter LIMIT in Cypher
Write rejectedConfirm the DB user has write privileges for neo4j_execute_write operations