Labsco
cxt9 logo

Neo4j

from cxt9

A server for accessing and interacting with a Neo4j graph database, configured via environment variables.

🔥🔥🔥✓ VerifiedFreeQuick setup
#database#devops#git

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.

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"

Tools exposed by the MCP server

ToolPurpose
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/