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

Tools exposed by the MCP server

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.