Neo4j MCP server
Neo4j's official MCP server lets agents introspect a graph schema and run read or write Cypher against any Neo4j deployment.
The Neo4j MCP server is Neo4j's official integration that gives a coding agent structured access to a Neo4j graph database over Cypher. Rather than blindly guessing at labels and relationship types, the agent first introspects the schema, then runs read-only Cypher to answer questions and, when permitted, write Cypher to mutate the graph. It works against every Neo4j deployment shape: Neo4j Aura, self-managed clusters, Docker, Neo4j Desktop, and Sandbox, so the same server fits local development and production alike.
Safety is built in. The read-cypher tool enforces read-only execution using EXPLAIN and Neo4j's own query-type classification, and write-cypher is disabled entirely when NEO4J_READ_ONLY is set to true, so you can hand an agent a production graph for exploration without write risk. It also exposes the Graph Data Science procedure catalog through list-gds-procedures so an agent can discover available algorithms before composing a query. The server runs locally over stdio, installs from PyPI as neo4j-mcp-server, and authenticates with standard NEO4J_URI, NEO4J_USERNAME, and NEO4J_PASSWORD environment variables plus optional database, telemetry, and logging settings.
Quick install
Copy-paste configs are provided for all 8 supported clients. Pick your client below.
Add to ~/.claude.json
{
"mcpServers": {
"neo4j": {
"command": "python",
"args": [
"-m",
"neo4j_mcp_server"
],
"env": {
"NEO4J_URI": "<NEO4J_URI>",
"NEO4J_USERNAME": "<NEO4J_USERNAME>",
"NEO4J_PASSWORD": "<NEO4J_PASSWORD>"
}
}
}
}claude mcp add neo4j -- python -m neo4j_mcp_serverAvailable tools
| Tool | Description |
|---|---|
| get-schema | Introspects the graph: labels, relationship types, and property keys, so the agent understands the model before querying. |
| read-cypher | Executes read-only Cypher queries, enforced via EXPLAIN and Neo4j's query-type classification so they cannot modify data. |
| write-cypher | Executes write Cypher queries that mutate the graph. Disabled when NEO4J_READ_ONLY is set to true. |
| list-gds-procedures | Lists the available Graph Data Science (GDS) procedures so the agent can discover algorithms before composing a query. |
Required configuration
- NEO4J_URIRequired
Connection URI for the Neo4j instance, e.g. bolt://localhost:7687.
- NEO4J_USERNAMERequired
Neo4j username used to authenticate.
- NEO4J_PASSWORDRequired
Password for the Neo4j user.
- NEO4J_DATABASEOptional
Target database name. Defaults to neo4j.
- NEO4J_READ_ONLYOptional
When true, disables write-cypher and restricts the server to read operations.
- NEO4J_TELEMETRYOptional
Enable or disable telemetry. Defaults to off.
- NEO4J_LOG_LEVELOptional
Logging verbosity, e.g. info or debug.
- NEO4J_SCHEMA_SAMPLE_SIZEOptional
Sample size used when introspecting the schema. Defaults to 100.
What you can do with it
Explore an unfamiliar graph safely
Point an agent at a Neo4j database with NEO4J_READ_ONLY set, let it call get-schema to learn the model, then answer questions with read-cypher with no risk of mutating data.
Generate and run graph queries
Ask the agent to translate a question into Cypher and execute it, using list-gds-procedures to discover graph algorithms for path-finding, centrality, or community detection.
FAQ
- Is it free?
- Yes. The Neo4j MCP server is open source and free to run; you only need a Neo4j database, which can be a free local instance, Neo4j Desktop, Sandbox, or a paid Aura or self-managed cluster.
- Can the agent modify my graph?
- Only if you allow it. read-cypher is enforced read-only via EXPLAIN, and write-cypher is disabled entirely when NEO4J_READ_ONLY is true, so you can run the server in a strictly read-only posture.
- Which Neo4j deployments does it support?
- All of them: Neo4j Aura, self-managed clusters, Docker, Neo4j Desktop, and Sandbox. You point it at any instance via the NEO4J_URI connection string.