Summary
Add a configurable transaction timeout for read queries (NEO4J_READ_TIMEOUT / --neo4j-read-timeout) to prevent complex analytical queries from failing against the default server-side timeout.
Problem
The neo4j-mcp server currently has no way to configure a transaction timeout for read queries executed via read-cypher. The Neo4j Go driver defaults to the server-side timeout, and when complex multi-hop Cypher queries exceed this limit, they fail with:
failed to execute read query: TransactionExecutionLimit: timeout (exceeded max retry time: 30s) after 1 attempts, last error: ConnectivityError: Timeout while reading from connection [server-side timeout hint: 1m0s, user-provided context deadline: N/A]: context deadline exceeded
There is no client-side workaround the only option today is to rewrite queries to be faster, which is not always possible for legitimate analytical workloads on large graphs.
Proposed Solution
Add a NEO4J_READ_TIMEOUT environment variable and --neo4j-read-timeout CLI flag (integer, in seconds, default: 30) that applies a transaction timeout to read queries.
The Go driver already supports this via neo4j.WithTxTimeout.
Expected Behavior
- Default behavior is unchanged (30-second timeout)
- Setting
NEO4J_READ_TIMEOUT=90 allows read queries up to 90 seconds
- CLI flag
--neo4j-read-timeout overrides the environment variable
- Existing setups remain backward-compatible
Prior work
The community MCP server (neo4j-contrib/mcp-neo4j, Python) has supported this since PR #163 via the same NEO4J_READ_TIMEOUT env var and --read-timeout CLI flag. Using the same env var name would provide consistency for users migrating between the two servers.
Use Case
We run an agentic LLM system that generates Cypher queries against a knowledge graph. Multi-hop analytical queries routinely take 30–90 seconds. The agent currently burns tool-call cycles retrying with progressively simpler queries until one fits within 30 seconds, which is wasteful and degrades response quality.
Environment
- neo4j-mcp version: v1.5.2
- Neo4j: Aura Professional (cloud-hosted)
- OS: Linux ARM64 (container)
Summary
Add a configurable transaction timeout for read queries (
NEO4J_READ_TIMEOUT/--neo4j-read-timeout) to prevent complex analytical queries from failing against the default server-side timeout.Problem
The neo4j-mcp server currently has no way to configure a transaction timeout for read queries executed via
read-cypher. The Neo4j Go driver defaults to the server-side timeout, and when complex multi-hop Cypher queries exceed this limit, they fail with:failed to execute read query: TransactionExecutionLimit: timeout (exceeded max retry time: 30s) after 1 attempts, last error: ConnectivityError: Timeout while reading from connection [server-side timeout hint: 1m0s, user-provided context deadline: N/A]: context deadline exceeded
There is no client-side workaround the only option today is to rewrite queries to be faster, which is not always possible for legitimate analytical workloads on large graphs.
Proposed Solution
Add a
NEO4J_READ_TIMEOUTenvironment variable and--neo4j-read-timeoutCLI flag (integer, in seconds, default:30) that applies a transaction timeout to read queries.The Go driver already supports this via
neo4j.WithTxTimeout.Expected Behavior
NEO4J_READ_TIMEOUT=90allows read queries up to 90 seconds--neo4j-read-timeoutoverrides the environment variablePrior work
The community MCP server (neo4j-contrib/mcp-neo4j, Python) has supported this since PR #163 via the same
NEO4J_READ_TIMEOUTenv var and--read-timeoutCLI flag. Using the same env var name would provide consistency for users migrating between the two servers.Use Case
We run an agentic LLM system that generates Cypher queries against a knowledge graph. Multi-hop analytical queries routinely take 30–90 seconds. The agent currently burns tool-call cycles retrying with progressively simpler queries until one fits within 30 seconds, which is wasteful and degrades response quality.
Environment