Neo4j MCP

A Model Context Protocol server that lets Claude (and other MCP clients) query and mutate Neo4j graph databases. Ships as both a standalone MCP server and a Claude Code plugin you can install once and reuse from any project.

Each project supplies its own Neo4j credentials via a local .env file, so the same plugin can target different databases depending on which folder Claude Code is opened in.

---

Features

• One consolidated cypher_query tool with explicit read / write mode.
• Schema introspection: labels, relationship types, and property keys.
• Full result serialization — preserves node/relationship element_id, labels, types, and Neo4j temporal/spatial values.
• Result-size guard with truncation flag, so a runaway MATCH (n) won't blow up the response.
• Per-project credentials through .env (loaded by python-dotenv from the working directory).
• Works with stdio (Claude Code, Claude Desktop, Cursor) and SSE.

Prerequisites

• Python 3.10+
• A reachable Neo4j database (local, Docker, or Aura)
• pip (or uv, pipx)

Install the Python package

The plugin shells out to a console script called neo4j-mcp-server, so the package needs to be on your PATH first.

git clone https://github.com/your-repo/neo4j-mcp.git cd neo4j-mcp pip install -e .

Verify it landed:

which neo4j-mcp-server neo4j-mcp-server --help

Tip: if you use pipx, pipx install -e . keeps the server isolated from your global Python.

Use it as a Claude Code plugin

The repo ships a plugin manifest at .claude-plugin/plugin.json. Once installed at the user level, the neo4j MCP server is available in every Claude Code session, on any project.

1. Install the plugin

From inside Claude Code:

/plugin install /absolute/path/to/neo4j-mcp

That registers the manifest globally. (You can also add it via a marketplace if you publish one — see Claude Code's plugin docs.)

2. Drop a .env in any project that should talk to Neo4j

The MCP server inherits Claude Code's working directory, so python-dotenv picks up whatever .env lives in that project's root. Different folders → different databases, no plugin reconfiguration needed.

my-project/.env

NEO4J_HOST=localhost NEO4J_PORT=7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=your-secret NEO4J_DATABASE=neo4j

For Aura / encrypted connections:

NEO4J_HOST=xxx.databases.neo4j.io NEO4J_PORT=7687 NEO4J_USERNAME=neo4j NEO4J_PASSWORD=your-aura-password NEO4J_URI_SCHEME=neo4j+s NEO4J_ENCRYPTED=true

For an unauthenticated local instance, leave NEO4J_USERNAME and NEO4J_PASSWORD blank.

Don't commit .env. Add it to .gitignore in every project.

3. Use it from Claude Code

Open the project, then ask Claude things like:

• "What labels and relationship types exist in this graph?"
• "Find the 10 most-connected Person nodes."
• "Create a Movie node titled Inception released in 2010."

Claude will call the cypher_query, get_database_schema, and test_database_connection tools as needed.

Use it without Claude Code

The same package works as a plain MCP server for any MCP-compatible client.

Claude Desktop / Cursor

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or your Cursor MCP config:

{ "mcpServers": { "neo4j": { "command": "neo4j-mcp-server", "args": [] } } }

Set the credentials by either putting a .env next to wherever the client launches the process, or by exporting NEO4J_* variables in the environment block.

SSE transport (web clients)

neo4j-mcp-server --transport sse --host 0.0.0.0 --port 3000

Standalone CLI

A small client is bundled for one-off testing:

neo4j-mcp-client --test neo4j-mcp-client --schema neo4j-mcp-client --query "MATCH (n) RETURN count(n) AS nodes" neo4j-mcp-client --write --query "CREATE (p:Person {name: 'Alice'}) RETURN p"

Configuration reference

All settings are read from environment variables (or a .env file in the working directory).

Variable	Default	Description
NEO4J_HOST	localhost	Bolt host
NEO4J_PORT	7687	Bolt port
NEO4J_HTTP_PORT	7474	Browser/HTTP port (informational)
NEO4J_USERNAME	(empty)	Leave blank for unauthenticated databases
NEO4J_PASSWORD	(empty)
NEO4J_DATABASE	neo4j	Default database
NEO4J_URI_SCHEME	bolt	One of bolt, bolt+s, neo4j, neo4j+s
NEO4J_ENCRYPTED	false	Set true for Aura / TLS
NEO4J_DEFAULT_RESULT_LIMIT	100	Row cap for read queries when none is supplied
NEO4J_MAX_CONNECTION_POOL_SIZE	100	Driver pool size
NEO4J_CONNECTION_TIMEOUT	30.0	Seconds

Tools exposed by the MCP server

Tool	Purpose
cypher_query(query, mode="read"|"write", parameters?, database?, limit?)	Run any Cypher query. Use mode="write" for CREATE/MERGE/SET/DELETE, even if you also RETURN rows. Returns {records, record_count, truncated, stats}.
get_database_schema(database?)	Returns labels, relationship types, and property keys.
test_database_connection()	Verifies connectivity, returns the server agent string and Bolt protocol version.

Resources: neo4j://schema, neo4j://connection. Prompt: cypher_query_help.

Development

pip install -e ".[dev]" pytest # 21 unit tests, no live database needed ruff check src/ tests/ mypy src/neo4j_mcp/

Troubleshooting

• Neo4j authentication failed — username/password mismatch. For unauthenticated DBs, leave both blank (don't set them to neo4j/neo4j).
• Neo4j service unavailable — DB is down or NEO4J_HOST / NEO4J_PORT are wrong. Try cypher-shell -a bolt://$NEO4J_HOST:$NEO4J_PORT to confirm.
• Plugin can't find neo4j-mcp-server — the console script isn't on the PATH that Claude Code inherits. Install with pipx or make sure your shell rc file exports the right PATH for GUI apps. On macOS, GUI apps don't read ~/.zshrc; use launchctl setenv PATH ... or install into /usr/local/bin.
• truncated: true on a read — bump limit on the call, or set NEO4J_DEFAULT_RESULT_LIMIT higher in .env.

---

MIT licensed.