mcp-neo4j-cypher MCP server for Claude Code: Cypher queries
MCP server that lets an agent run Cypher queries against Neo4j and pull the graph schema.
claude mcp add --env NEO4J_URI=<NEO4J_URI> --env NEO4J_USERNAME=<NEO4J_USERNAME> --env NEO4J_PASSWORD=<NEO4J_PASSWORD> --env NEO4J_DATABASE=<NEO4J_DATABASE> --env NEO4J_NAMESPACE=<NEO4J_NAMESPACE> --transport stdio mcp-neo4j-cypher -- uvx mcp-neo4j-cypherWhat mcp-neo4j-cypher does
Three tools come with this server. read_neo4j_cypher runs read queries and hands results back as a JSON array; write_neo4j_cypher handles updates and answers with counters for touched nodes and created relationships. The third one, get_neo4j_schema, lists node labels with their attributes and the relationships between them.
Schema inspection needs the APOC plugin enabled on the instance. Without it get_neo4j_schema fails. You also need a live Neo4j database, Aura or self-managed. Read queries carry a 30 second timeout by default, changed with --read-timeout or NEO4J_READ_TIMEOUT. Response size is capped by --token-limit and NEO4J_RESPONSE_TOKEN_LIMIT, and tiktoken cuts anything longer.
Running against more than one database? Set a namespace and every tool name gets a prefix such as mydb-read_neo4j_cypher. The --read-only flag, or NEO4J_READ_ONLY=true, removes the write tool from what the agent sees. On a large graph keep schema sampling low: 1000 nodes per label is the default, -1 scans everything.
What it helps with
- pull a subset of the graph with a Cypher query
- patch nodes and relationships from the chat window
- read the labels and edges before writing a query
- keep a huge result inside the model token budget
- talk to two Neo4j instances in one session
Example prompts for the agent
- Run a Cypher query in Neo4j: which
Customernodes link to order 42? - Describe the schema of the
mydbdatabase - Create a
Projectnode called “NeVibe” and connect it to its owner
How to install mcp-neo4j-cypher
Platform CLI
claude mcp add --env NEO4J_URI=<NEO4J_URI> --env NEO4J_USERNAME=<NEO4J_USERNAME> --env NEO4J_PASSWORD=<NEO4J_PASSWORD> --env NEO4J_DATABASE=<NEO4J_DATABASE> --env NEO4J_NAMESPACE=<NEO4J_NAMESPACE> --transport stdio mcp-neo4j-cypher -- uvx mcp-neo4j-cypherReplace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-neo4j-cypher <command>
Platform CLI
codex mcp add mcp-neo4j-cypher --env NEO4J_URI=<NEO4J_URI> --env NEO4J_USERNAME=<NEO4J_USERNAME> --env NEO4J_PASSWORD=<NEO4J_PASSWORD> --env NEO4J_DATABASE=<NEO4J_DATABASE> --env NEO4J_NAMESPACE=<NEO4J_NAMESPACE> -- uvx mcp-neo4j-cypherReplace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-neo4j-cypher <command>
Config file
{
"mcpServers": {
"mcp-neo4j-cypher": {
"command": "uvx",
"args": [
"mcp-neo4j-cypher"
],
"env": {
"NEO4J_URI": "<NEO4J_URI>",
"NEO4J_USERNAME": "<NEO4J_USERNAME>",
"NEO4J_PASSWORD": "<NEO4J_PASSWORD>",
"NEO4J_DATABASE": "<NEO4J_DATABASE>",
"NEO4J_NAMESPACE": "<NEO4J_NAMESPACE>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-neo4j-cypher <command>
Config file
{
"servers": {
"mcp-neo4j-cypher": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-neo4j-cypher"
],
"env": {
"NEO4J_URI": "<NEO4J_URI>",
"NEO4J_USERNAME": "<NEO4J_USERNAME>",
"NEO4J_PASSWORD": "<NEO4J_PASSWORD>",
"NEO4J_DATABASE": "<NEO4J_DATABASE>",
"NEO4J_NAMESPACE": "<NEO4J_NAMESPACE>"
}
}
}
}Replace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-neo4j-cypher <command>
Platform CLI
gemini mcp add -e NEO4J_URI=<NEO4J_URI> -e NEO4J_USERNAME=<NEO4J_USERNAME> -e NEO4J_PASSWORD=<NEO4J_PASSWORD> -e NEO4J_DATABASE=<NEO4J_DATABASE> -e NEO4J_NAMESPACE=<NEO4J_NAMESPACE> mcp-neo4j-cypher uvx mcp-neo4j-cypherReplace <…> with your own values. 4 more environment variables are in the server README. uvx runs the command named after the package; if the README names another one, use uvx --from mcp-neo4j-cypher <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-neo4j-cypher
How do I install mcp-neo4j-cypher in Claude Code?
Run `claude mcp add mcp-neo4j-cypher -e NEO4J_URI=<NEO4J_URI> -e NEO4J_USERNAME=<NEO4J_USERNAME> -e NEO4J_PASSWORD=<NEO4J_PASSWORD> -- uvx mcp-neo4j-cypher`, replacing the placeholders with your connection details.
What does mcp-neo4j-cypher do?
It exposes read and write Cypher execution plus graph schema extraction to the agent, so a plain-language question turns into a query against Neo4j.
Can I keep the agent from writing to the database?
Yes. Start the server with --read-only or set NEO4J_READ_ONLY=true, and the write tool is no longer offered.
